设计说明: 枚举规范

在 OneAdmin 的分层架构中，枚举作为基础能力的一部分存在，用于统一表达“取值有限”的数据类型。通过引入枚举，可以有效避免在代码中使用硬编码，提高代码的可读性与可维护性，同时保证系统中同一语义的表达一致。

设计原则#

在以下场景中，建议使用枚举：

• 某个字段取值范围有限（如状态、性别、开关等）
• 多个模块共享同一语义的数据
• 需要与多语言展示结合

所有枚举统一定义在：

internal/enum

作为全局通用模块使用。

基础枚举结构#

一个标准的枚举定义如下：

type YesNo int

const (
	No YesNo = iota
	Yes
)

func (y YesNo) Key() string {
	switch y {
	case No:
		return "no"
	case Yes:
		return "yes"
	default:
		return "unknown"
	}
}

func (y YesNo) Text(lang string) string {
	return i18n.T(lang, y.Key())
}

func (y YesNo) IsValid() bool {
	switch y {
	case No, Yes:
		return true
	default:
		return false
	}
}

方法约定#

每个枚举通常应实现以下三个方法：

1. Key() string

   • 返回枚举对应的 i18n key
   • 用于与多语言模块对接

2. Text(lang string) string

   • 返回当前语言下的枚举文本
   • 实际调用 i18n 模块进行转换

3. IsValid() bool

   • 用于校验枚举值是否合法
   • 常用于请求参数校验

与多语言的结合#

枚举通过 Key() 方法与多语言模块解耦：

• 枚举只负责返回 key
• 文本内容由 i18n 决定

示例：

text := Yes.Text("en")

这种设计可以保证：

• 枚举逻辑与展示内容分离
• 同一枚举在不同语言下自动适配

类型选择建议#

枚举类型可以根据实际情况定义为：

• int
• string

建议：尽量与数据库字段类型保持一致

例如：

• 数据库中为 tinyint → 使用 int 枚举
• 数据库中为 varchar → 使用 string 枚举

约定规范#

在实际开发中，建议遵循以下规则：

1. 避免硬编码

   • 不直接使用 0 / 1 / 2 等魔法值
   • 统一通过枚举表达语义

2. 全局统一语义

   • 同一含义的枚举在全系统中保持一致
   • 不允许不同模块使用不同编码规则

   例如（错误示例）：

   • A 模块：0 = 女，1 = 男
   • B 模块：1 = 男，2 = 女

3. 参数校验必须使用 IsValid

   • 所有外部输入的枚举值必须校验合法性

4. 避免在业务层重复定义枚举

   • 枚举应集中在 internal/enum 中统一管理