完成领域相关文档的添加

framework/core/domain/entity/entity.go

@@ -4,11 +4,22 @@ import (
 	"git.sxidc.com/go-framework/baize/framework/core/domain"
 )
 
+// Entity 领域实体接口
 type Entity interface {
 	domain.Object
+
+	// GenerateID 生成ID
 	GenerateID() error
+
+	// GetID 获取ID
 	GetID() string
+
+	// ForCreate 创建准备方法(规则校验)
 	ForCreate() error
+
+	// ForDelete 删除准备方法(规则校验)
 	ForDelete() error
+
+	// ForUpdate 更新准备方法(规则校验)
 	ForUpdate() error
 }

framework/core/domain/entity/field.go

@@ -8,69 +8,157 @@ import (
 )
 
 const (
-	FieldID               = "ID"
-	FieldTenantID         = "TenantID"
-	FieldCreateUserID     = "CreateUserID"
+	// FieldID ID字段名
+	FieldID = "ID"
+
+	// FieldTenantID 租户ID字段名
+	FieldTenantID = "TenantID"
+
+	// FieldCreateUserID 创建用户ID字段名
+	FieldCreateUserID = "CreateUserID"
+
+	// FieldLastUpdateUserID 最近更新用户ID字段名
 	FieldLastUpdateUserID = "LastUpdateUserID"
-	FieldCreatedTime      = "CreatedTime"
-	FieldLastUpdatedTime  = "LastUpdatedTime"
+
+	// FieldCreatedTime 创建时间字段名
+	FieldCreatedTime = "CreatedTime"
+
+	// FieldLastUpdatedTime 最近更新时间字段名
+	FieldLastUpdatedTime = "LastUpdatedTime"
 )
 
 const (
-	ColumnID               = "id"
-	ColumnTenantID         = "tenant_id"
-	ColumnCreateUserID     = "create_user_id"
+	// ColumnID ID列名
+	ColumnID = "id"
+
+	// ColumnTenantID 租户ID列名
+	ColumnTenantID = "tenant_id"
+
+	// ColumnCreateUserID 创建用户ID列名
+	ColumnCreateUserID = "create_user_id"
+
+	// ColumnLastUpdateUserID 最新更新用户ID列名
 	ColumnLastUpdateUserID = "last_update_user_id"
-	ColumnCreatedTime      = "created_time"
-	ColumnLastUpdatedTime  = "last_updated_time"
+
+	// ColumnCreatedTime 创建时间列名
+	ColumnCreatedTime = "created_time"
+
+	// ColumnLastUpdatedTime 最近更新时间列名
+	ColumnLastUpdatedTime = "last_updated_time"
 )
 
+const (
+	idLen = 32
+)
+
+// TenantIDField 租户ID字段
 type TenantIDField struct {
 	TenantID string `sqlmapping:"column:tenant_id;" sqlresult:"column:tenant_id;" check:"required,len=32"`
 }
 
+// UserIDFields 用户ID相关字段
 type UserIDFields struct {
 	CreateUserID     string `sqlmapping:"column:create_user_id;" sqlresult:"column:create_user_id;" check:"required,len=32"`
 	LastUpdateUserID string `sqlmapping:"column:last_update_user_id;" sqlresult:"column:last_update_user_id;" check:"required,len=32"`
 }
 
+// TimeFields 时间相关字段
 type TimeFields struct {
 	CreatedTime     time.Time `sqlmapping:"column:created_time;" sqlresult:"column:created_time;"`
 	LastUpdatedTime time.Time `sqlmapping:"column:last_updated_time;" sqlresult:"column:last_updated_time;"`
 }
 
+// CheckFieldID 校验领域实体的ID字段是否合规
+// 参数:
+// - entity: 领域实体
+// 返回值:
+// - 错误
 func CheckFieldID(entity Entity) error {
 	return checkIDTypeField(entity, FieldID, "ID")
 }
 
+// CheckFieldTenantID 校验领域实体的租户ID字段是否合规
+// 参数:
+// - entity: 领域实体
+// 返回值:
+// - 错误
 func CheckFieldTenantID(entity Entity) error {
 	return checkIDTypeField(entity, FieldTenantID, "租户ID")
 }
 
+// CheckFieldCreateUserID 校验领域实体的创建用户ID字段是否合规
+// 参数:
+// - entity: 领域实体
+// 返回值:
+// - 错误
 func CheckFieldCreateUserID(entity Entity) error {
 	return checkIDTypeField(entity, FieldCreateUserID, "创建用户ID")
 }
 
+// CheckFieldLastUpdateUserID 校验领域实体的最近更新用户ID字段是否合规
+// 参数:
+// - entity: 领域实体
+// 返回值:
+// - 错误
 func CheckFieldLastUpdateUserID(entity Entity) error {
 	return checkIDTypeField(entity, FieldLastUpdateUserID, "最近更新用户ID")
 }
 
+// CheckFieldIDResult 利用check.Struct函数返回的结果校验领域实体的ID字段是否合规
+// 参数:
+// - checkResult: check.Struct函数返回的结果
+// 返回值:
+// - 错误
 func CheckFieldIDResult(checkResult check.Result) error {
 	return checkIDTypeResult(checkResult, FieldID, FieldID)
 }
 
+// CheckFieldTenantIDResult 利用check.Struct函数返回的结果校验领域实体的租户ID字段是否合规
+// 参数:
+// - checkResult: check.Struct函数返回的结果
+// 返回值:
+// - 错误
 func CheckFieldTenantIDResult(checkResult check.Result) error {
 	return checkIDTypeResult(checkResult, FieldTenantID, FieldTenantID)
 }
 
+// CheckFieldCreateUserIDResult 利用check.Struct函数返回的结果校验领域实体的创建用户ID字段是否合规
+// 参数:
+// - checkResult: check.Struct函数返回的结果
+// 返回值:
+// - 错误
 func CheckFieldCreateUserIDResult(checkResult check.Result) error {
 	return checkIDTypeResult(checkResult, FieldCreateUserID, FieldCreateUserID)
 }
 
+// CheckFieldLastUpdateUserIDResult 利用check.Struct函数返回的结果校验领域实体的最近更新用户ID字段是否合规
+// 参数:
+// - checkResult: check.Struct函数返回的结果
+// 返回值:
+// - 错误
 func CheckFieldLastUpdateUserIDResult(checkResult check.Result) error {
 	return checkIDTypeResult(checkResult, FieldLastUpdateUserID, FieldLastUpdateUserID)
 }
 
+// CheckIDTypeValue 校验ID类型的字段，如ID，租户ID，用户ID等，特点是字符串类型，不能为空且长度严格为32字节
+// 参数:
+// - domainCNName: 领域中文名，可以使用DomainCNName()方法获得
+// - fieldCNName: 字段的中文名称(用于构造报错信息)
+// - id: id字段的值
+// 返回值:
+// - 错误
+func CheckIDTypeValue(domainCNName string, fieldCNName string, id string) error {
+	if strutils.IsStringEmpty(id) {
+		return errors.New(domainCNName + fieldCNName + "为空")
+	}
+
+	if len(id) != idLen {
+		return errors.New(domainCNName + fieldCNName + "长度不正确")
+	}
+
+	return nil
+}
+
 func checkIDTypeField(entity Entity, fieldName string, fieldCNName string) error {
 	checkResult := check.Struct(entity, map[string]string{
 		fieldName: entity.DomainCNName() + fieldCNName,
@@ -92,19 +180,3 @@ func checkIDTypeResult(checkResult check.Result, domainCNName string, fieldName
 
 	return nil
 }
-
-const (
-	idLen = 32
-)
-
-func CheckIDTypeValue(domainCNName string, fieldCNName string, id string) error {
-	if strutils.IsStringEmpty(id) {
-		return errors.New(domainCNName + fieldCNName + "为空")
-	}
-
-	if len(id) != idLen {
-		return errors.New(domainCNName + fieldCNName + "长度不正确")
-	}
-
-	return nil
-}

framework/core/domain/object.go

@@ -10,16 +10,35 @@ import (
 	"reflect"
 )
 
+// Object 领域对象接口
 type Object interface {
+	// DBSchema 返回针对领域的数据库的schema，一般不需要赋值，除非该领域对象与其他领域对象不在同一个schema
 	DBSchema() string
+
+	// DomainCNName 返回领域的中文名称
 	DomainCNName() string
+
+	// DomainCamelName 返回领域的大写驼峰式名称
 	DomainCamelName() string
 }
 
+// HasField 校验领域对象中是否有某一个字段
+// 参数:
+// - object: 领域对象
+// - fieldName: 字段名
+// 返回值:
+// - 是否存在
 func HasField(object Object, fieldName string) bool {
 	return hasField(object, fieldName)
 }
 
+// CheckField 校验领域对象某一字段的字段校验结果
+// 参数:
+// - result: 使用check.Struct返回的字段校验结果
+// - domainCNName: 领域中文名，可以使用DomainCNName()方法的返回值
+// - fieldName: 字段名
+// 返回值:
+// - 错误
 func CheckField(result check.Result, domainCNName string, fieldName string) error {
 	err := result.CheckFields(fieldName)
 	if err != nil {
@@ -29,6 +48,13 @@ func CheckField(result check.Result, domainCNName string, fieldName string) erro
 	return nil
 }
 
+// CheckFields 校验领域对象多个字段的字段校验结果
+// 参数:
+// - result: 使用check.Struct返回的字段校验结果
+// - domainCNName: 领域中文名，可以使用DomainCNName()方法的返回值
+// - fieldNames: 多个字段名
+// 返回值:
+// - 错误
 func CheckFields(result check.Result, domainCNName string, fieldNames []string) error {
 	err := result.CheckFields(fieldNames...)
 	if err != nil {
@@ -38,6 +64,15 @@ func CheckFields(result check.Result, domainCNName string, fieldNames []string)
 	return nil
 }
 
+// SetField 设置领域对象对应字段的值
+// 类型参数：
+// - T: 字段值的类型
+// 参数:
+// - object: 领域对象
+// - fieldName: 要设置值的字段名
+// - value: 设置的值
+// 返回值:
+// - 错误
 func SetField[T any](object Object, fieldName string, value T) error {
 	if object == nil {
 		return errors.New("领域对象为nil")
@@ -57,6 +92,14 @@ func SetField[T any](object Object, fieldName string, value T) error {
 	return nil
 }
 
+// Field 获取领域对象对应字段的值
+// 类型参数：
+// - T: 字段值的类型
+// 参数:
+// - object: 领域对象
+// - fieldName: 要获取值的字段名
+// 返回值:
+// - 错误
 func Field[T any](object Object, fieldName string) (T, error) {
 	zero := reflectutils.Zero[T]()
 
@@ -81,6 +124,14 @@ func Field[T any](object Object, fieldName string) (T, error) {
 	return retValue, nil
 }
 
+// ToConcrete 将领域对象转换为具体类型
+// 类型参数：
+// - T: 要转换到的类型
+// 参数:
+// - object: 领域对象
+// 返回值:
+// - 转换出的类型
+// - 错误
 func ToConcrete[T Object](object Object) (T, error) {
 	zero := reflectutils.Zero[T]()
 
@@ -96,6 +147,12 @@ func ToConcrete[T Object](object Object) (T, error) {
 	return concrete, nil
 }
 
+// TableName 基于领域对象生成表名，实际是将领域对象的驼峰式名称转换为蛇形复数形式，如classes
+// 参数:
+// - schema: 数据库的schema，如果领域对象DBSchema()方法返回值不为空，则取代schema参数
+// - object: 领域对象
+// 返回值:
+// - 表名
 func TableName(schema string, object Object) string {
 	if strutils.IsStringNotEmpty(object.DBSchema()) {
 		schema = object.DBSchema()
@@ -108,7 +165,18 @@ func TableName(schema string, object Object) string {
 	}
 }
 
+// RelationTableName 生成两个领域对象的关联表名，实际是将两个领域对象的驼峰式名称转换为蛇形并使用and连接，如:class_and_student
+// 参数:
+// - schema: 数据库的schema，如果schema为空，但是两个领域对象的DBSchema()方法返回值不为空切一致，则取代schema参数
+// - left: 左领域对象
+// - right: 右领域对象
+// 返回值:
+// - 关联表名
 func RelationTableName(schema string, left Object, right Object) string {
+	if strutils.IsStringNotEmpty(left.DBSchema()) && left.DBSchema() == right.DBSchema() {
+		schema = left.DBSchema()
+	}
+
 	if strutils.IsStringEmpty(schema) {
 		return strcase.ToSnake(template.Id(left.DomainCamelName())) + "_and_" + strcase.ToSnake(template.Id(right.DomainCamelName()))
 	} else {
@@ -116,18 +184,38 @@ func RelationTableName(schema string, left Object, right Object) string {
 	}
 }
 
+// ColumnName 生成对应字段的列名，实际为字段名转换为蛇形，如StudentNum会转化为student_num
+// 参数:
+// - fieldName: 字段名
+// 返回值:
+// - 列名
 func ColumnName(fieldName string) string {
 	return strcase.ToSnake(template.Id(fieldName))
 }
 
+// RelationColumnName 基于领域对象生成关联列名，实际为字段名转换为蛇形后加_id，如Student生成的关联列名为student_id
+// 参数:
+// - object: 领域对象
+// 返回值:
+// - 关联列名
 func RelationColumnName(object Object) string {
 	return strcase.ToSnake(template.Id(object.DomainCamelName())) + "_id"
 }
 
+// RelativeDomainPath 基于领域对象生成领域URL路径，实际为字段名转换为左小写驼峰式前面加/，如Student生成的领域URL路径为/student
+// 参数:
+// - object: 领域对象
+// 返回值:
+// - 领域URL路径
 func RelativeDomainPath(object Object) string {
 	return "/" + strcase.ToLowerCamel(template.Id(object.DomainCamelName()))
 }
 
+// SnakeDomainName 基于领域对象生成蛇形领域名称，如Student生成的蛇形领域名称为/student
+// 参数:
+// - object: 领域对象
+// 返回值:
+// - 蛇形领域名称
 func SnakeDomainName(object Object) string {
 	return strcase.ToSnake(template.Id(object.DomainCamelName()))
 }

framework/core/domain/value_object/value_object.go

@@ -2,8 +2,13 @@ package value_object
 
 import "git.sxidc.com/go-framework/baize/framework/core/domain"
 
+// ValueObject 值对象接口
 type ValueObject interface {
 	domain.Object
+
+	// CheckKeyFields 校验关键字段，关键字段值能够唯一标识一个值对象的联合主键字段
 	CheckKeyFields() error
+
+	// ForCreate 创建准备方法(规则校验)
 	ForCreate() error
 }