entities

README

entities — Ent Schema 基础 Mixin

提供所有业务实体共用的 Ent ORM Mixin，统一主键格式、审计字段与多租户隔离字段。

Mixin 列表

Mixin	用途	额外字段
AuditedEntitySchema	基础审计字段	无额外字段，仅包含标准审计字段
BaseEntitySchema	领域隔离实体（推荐）	ownerDomainId
GlobalEntitySchema	全局/平台级实体（无域隔离）	无
TenantEntitySchema	多租户实体	tenantId（NOT NULL）

共用审计字段

所有 Mixin 均包含以下字段：

字段	类型	说明
id	UUID v7	主键，不可变
createdById	UUID	创建者 ID
createdAt	Time	创建时间
updatedById	UUID	更新者 ID
updatedAt	Time	更新时间
deletedById	UUID	软删除者 ID
deletedAt	Time	软删除时间
publishedAt	Time	发布时间
archivedAt	Time	归档时间

使用方式

package schema

import (
    "entgo.io/ent"
    "github.com/leeforge/framework/entities"
)

// 继承 BaseEntitySchema（推荐）
type Article struct {
    entities.BaseEntitySchema
}

func (Article) Fields() []ent.Field {
    // 当使用外键 Edge 时，必须显式定义 id 字段
    return []ent.Field{
        entities.IDField("id"),
    }
}

func (Article) Edges() []ent.Edge {
    return []ent.Edge{
        // 定义外键关系
    }
}

UUID v7 生成

框架提供 NewUUID() 函数生成有序的 UUID v7（时间戳有序，天然支持数据库索引优化）：

import "github.com/leeforge/framework/entities"

id := entities.NewUUID() // 生成 UUID v7

// 在 Schema 中使用
field.UUID("id", uuid.UUID{}).Default(entities.NewUUID).Immutable()

禁止直接调用第三方 UUID 库，必须使用此 NewUUID()，保证全局 ID 格式一致。

状态枚举

// 内容发布状态
entities.Draft     // "draft"
entities.Published // "published"
entities.Archived  // "archived"

// 激活状态
entities.StatusActive   // "active"
entities.StatusInactive // "inactive"

索引

AuditedEntitySchema 自动创建以下索引：

• id（主键）
• deleted_at（软删除过滤）
• created_at / updated_at / published_at（时间排序）

注意事项

• 使用 BaseEntitySchema 且涉及 Edge 外键时，必须在子 Schema 中显式调用 entities.IDField("id") 定义主键，否则 Ent 可能回退到 int 类型
• 软删除逻辑由业务层自行实现（框架不自动过滤 deleted_at != null），建议配合 Ent Interceptor 使用

Documentation

Index

• func DeletedAtHook(next ent.Mutator) ent.Mutator
• func IDField(fieldName string) ent.Field
• func NewUUID() uuid.UUID
• func UpdatedAtHook(next ent.Mutator) ent.Mutator
• func WithStatus(ctx context.Context, status Status) context.Context
• type ActiveStatus
  • func (s *ActiveStatus) Scan(value any) error
  • func (s ActiveStatus) Value() (driver.Value, error)
• type ActiveStatusSchema
  • func (ActiveStatusSchema) Fields() []ent.Field
• type AuditedEntitySchema
  • func (AuditedEntitySchema) Fields() []ent.Field
  • func (AuditedEntitySchema) Indexes() []ent.Index
• type BaseEntitySchema
  • func (BaseEntitySchema) Fields() []ent.Field
  • func (BaseEntitySchema) Indexes() []ent.Index
• type DomainScopeMixin
  • func (DomainScopeMixin) Fields() []ent.Field
  • func (DomainScopeMixin) Indexes() []ent.Index
• type GlobalEntitySchema
  • func (GlobalEntitySchema) Fields() []ent.Field
  • func (GlobalEntitySchema) Indexes() []ent.Index
• type Media
  • func (Media) Edges() []ent.Edge
  • func (Media) Fields() []ent.Field
  • func (Media) Indexes() []ent.Index
  • func (Media) Mixin() []ent.Mixin
• type MediaFormat
  • func (MediaFormat) Edges() []ent.Edge
  • func (MediaFormat) Fields() []ent.Field
  • func (MediaFormat) Indexes() []ent.Index
  • func (MediaFormat) Mixin() []ent.Mixin
• type Status
  • func StatusFromContext(ctx context.Context) (Status, bool)
• type StatusContextKey
• type TenantEntitySchema
  • func (TenantEntitySchema) Fields() []ent.Field
  • func (TenantEntitySchema) Indexes() []ent.Index

Functions

func DeletedAtHook

func DeletedAtHook(next ent.Mutator) ent.Mutator

func IDField

func IDField(fieldName string) ent.Field

IDField creates a UUID field with standard configuration. fieldName should be the database field name in snake_case (e.g., "id", "created_by_id"). The JSON tag will be converted to lowerCamelCase (e.g., "id", "createdById").

func NewUUID

func NewUUID() uuid.UUID

NewUUID generates a new UUID v7. It panics if the generation fails, as UUID v7 generation should not fail in normal circumstances.

func UpdatedAtHook

func UpdatedAtHook(next ent.Mutator) ent.Mutator

func WithStatus

func WithStatus(ctx context.Context, status Status) context.Context

Types

type ActiveStatus

type ActiveStatus string

const (
	StatusActive   ActiveStatus = "active"
	StatusInactive ActiveStatus = "inactive"
)

func (*ActiveStatus) Scan

func (s *ActiveStatus) Scan(value any) error

func (ActiveStatus) Value

func (s ActiveStatus) Value() (driver.Value, error)

type ActiveStatusSchema

type ActiveStatusSchema struct {
	mixin.Schema
}

func (ActiveStatusSchema) Fields

func (ActiveStatusSchema) Fields() []ent.Field

type AuditedEntitySchema

type AuditedEntitySchema struct {
	mixin.Schema
}

AuditedEntitySchema defines shared id/audit fields without tenant scoping.

func (AuditedEntitySchema) Fields

func (AuditedEntitySchema) Fields() []ent.Field

func (AuditedEntitySchema) Indexes

func (AuditedEntitySchema) Indexes() []ent.Index

type BaseEntitySchema

type BaseEntitySchema struct {
	AuditedEntitySchema
}

func (BaseEntitySchema) Fields

func (BaseEntitySchema) Fields() []ent.Field

Fields returns domain-scoped entity fields (id + audit + owner_domain_id).

func (BaseEntitySchema) Indexes

func (BaseEntitySchema) Indexes() []ent.Index

Indexes returns domain-scoped entity indexes.

type DomainScopeMixin

type DomainScopeMixin struct {
	mixin.Schema
}

DomainScopeMixin adds an optional owner_domain_id field for domain-scoped data isolation. Entities using this mixin can be filtered by the DomainInterceptor based on the acting domain.

func (DomainScopeMixin) Fields

func (DomainScopeMixin) Fields() []ent.Field

func (DomainScopeMixin) Indexes

func (DomainScopeMixin) Indexes() []ent.Index

type GlobalEntitySchema

type GlobalEntitySchema struct {
	AuditedEntitySchema
}

GlobalEntitySchema defines global/platform-scoped entities.

func (GlobalEntitySchema) Fields

func (GlobalEntitySchema) Fields() []ent.Field

Fields returns global/platform entity fields.

func (GlobalEntitySchema) Indexes

func (GlobalEntitySchema) Indexes() []ent.Index

Indexes returns global/platform entity indexes.

type Media

type Media struct {
	ent.Schema
}

func (Media) Edges

func (Media) Edges() []ent.Edge

func (Media) Fields

func (Media) Fields() []ent.Field

func (Media) Indexes

func (Media) Indexes() []ent.Index

func (Media) Mixin

func (Media) Mixin() []ent.Mixin

type MediaFormat

type MediaFormat struct {
	ent.Schema
}

func (MediaFormat) Edges

func (MediaFormat) Edges() []ent.Edge

func (MediaFormat) Fields

func (MediaFormat) Fields() []ent.Field

func (MediaFormat) Indexes

func (MediaFormat) Indexes() []ent.Index

func (MediaFormat) Mixin

func (MediaFormat) Mixin() []ent.Mixin

type Status

type Status string

const (
	Draft     Status = "draft"
	Published Status = "published"
	Archived  Status = "archived"
)

func StatusFromContext

func StatusFromContext(ctx context.Context) (Status, bool)

type StatusContextKey

type StatusContextKey struct{}

type TenantEntitySchema

type TenantEntitySchema struct {
	AuditedEntitySchema
}

TenantEntitySchema defines tenant-scoped entities.

func (TenantEntitySchema) Fields

func (TenantEntitySchema) Fields() []ent.Field

Fields returns tenant-scoped fields and requires explicit tenant assignment.

func (TenantEntitySchema) Indexes

func (TenantEntitySchema) Indexes() []ent.Index

Indexes returns tenant-scoped indexes.