小蚂蚁云

参数管理

参数管理模块用于管理动态系统参数，与系统配置模块类似但更侧重于业务参数的灵活配置。支持按参数键查询、修改，无需重启服务即可生效。本模块是典型的「BaseService 简单模块」，通过声明差异点即可获得完整 CRUD 能力。

模块结构

src/modules/param/
├── models.py     # 参数模型
├── schemas.py    # 表单验证
├── repository.py # 数据访问层
└── service.py    # 业务逻辑层（继承 BaseService）

参数模型

python

# src/modules/param/models.py
class Param(base_model, base_db):
    """参数模型类"""
    __tablename__ = DB_PREFIX + "param"
    __table_comment__ = "系统参数表"

    # 参数名称
    name = Column(String(100), nullable=False, index=True, comment="参数名称")
    # 参数编码（唯一标识，用于业务代码中按编码取值）
    code = Column(String(100), nullable=False, index=True, comment="参数编码")
    # 参数值
    value = Column(String(255), nullable=False, comment="参数值")
    # 参数类型：0-系统 1-业务
    type = Column(Integer, nullable=False, comment="参数类型：0-系统 1-业务")
    # 参数状态：1-正常 2-禁用
    status = Column(Integer, nullable=False, index=True, comment="参数状态：1-正常 2-禁用")
    # 参数排序
    sort = Column(Integer, nullable=False, comment="参数排序")
    # 参数备注
    note = Column(String(255), nullable=True, comment="参数备注")

其中 id、create_user、create_time、update_user、update_time、is_delete 由基类 base_model 自动提供。

表单验证

python

class ParamForm(BaseForm):
    name: str = Field(..., min_length=1, max_length=100, description="参数名称")
    code: str = Field(..., min_length=1, max_length=100, description="参数编码")
    value: str = Field(..., min_length=1, max_length=255, description="参数值")
    type: int = Field(..., ge=0, le=1, description="参数类型：0-系统 1-业务")
    status: int = Field(..., ge=1, le=2, description="参数状态：1-正常 2-禁用")
    sort: int = Field(..., ge=0, le=99999, description="参数排序")
    note: Optional[str] = Field(None, max_length=255, description="参数备注")

字段	必填	约束	说明
`name`	是	`1~100 字符`	参数名称，唯一
`code`	是	`1~100 字符`	参数编码，唯一，业务代码中按此取值
`value`	是	`1~255 字符`	参数值，字符串类型
`type`	是	`0~1`	0=系统参数，1=业务参数
`status`	是	`1~2`	1=正常，2=禁用（注意：非 0/1）
`sort`	是	`0~99999`	排序号，值越大越靠前
`note`	否	`max_length=255`	备注说明

status 字段的取值范围

参数模块的 status 使用 1=正常, 2=禁用，与文章模块的 0=正常, 1=下架 不同。这是历史约定，开发时需注意区分。

Service 层设计

继承 BaseService

参数模块是典型的 BaseService 简单模块，只需声明差异点即可获得完整 CRUD 能力：

python

class ParamService(BaseService[Param]):
    """参数业务服务类，继承基础服务获得通用 CRUD 能力"""

    # ============ 必须声明 ============
    repo = param_repo           # 数据访问层实例
    model = Param               # 模型类

    # ============ 分页差异点 ============
    page_like_fields = ('name', 'code')           # 模糊搜索字段
    page_eq_fields = ('type', 'status')           # 等值搜索字段
    page_order_by = (('sort', 'asc'), ('id', 'desc'))  # 排序规则

    # ============ 唯一性校验 ============
    unique_fields = {
        'name': '参数名称不能重复',
        'code': '参数编码不能重复'
    }

    # ============ 枚举显示名映射 ============
    serialize_maps = {
        'type': 'param_type',      # 参数类型 → 数据字典
        'status': 'param_status'   # 参数状态 → 数据字典
    }

    # ============ 自定义方法 ============
    def get_value_by_code(self, code: str, default: Optional[str] = None) -> Optional[str]:
        """根据参数编码获取参数值"""
        param = self.repo.get_one(code=code, status=1)
        return param.value if param else default

差异点详解

page_like_fields（模糊搜索）

声明后，BaseService 自动从 request.query_params 中取同名参数做 LIKE %值% 查询：

python

# 声明 page_like_fields = ('name', 'code') 后
# 请求 GET /api/v1/param/page?name=默认&code=PASSWORD
# 自动生成：WHERE name LIKE '%默认%' AND code LIKE '%PASSWORD%'

page_eq_fields（等值搜索）

声明后，自动取同名参数做精确匹配：

python

# 声明 page_eq_fields = ('type', 'status') 后
# 请求 GET /api/v1/param/page?type=0&status=1
# 自动生成：WHERE type = 0 AND status = 1

page_order_by（排序规则）

python

# 声明 page_order_by = (('sort', 'asc'), ('id', 'desc'))
# 生成：ORDER BY sort ASC, id DESC
# 即排序号越小越靠前，同排序号时新记录在前

unique_fields（唯一性校验）

python

# 声明 unique_fields = {'name': '参数名称不能重复', 'code': '参数编码不能重复'}
# 新增时：查询是否存在同名/同编码记录
# 编辑时：查询是否存在同名/同编码记录（排除自身 ID）
# 若重复：返回 R.failed('参数名称不能重复')

BaseService 内部自动调用 repo.exists_by_field(field, value, exclude_id) 实现，无需手写校验逻辑。

serialize_maps（枚举显示名映射）

python

# 声明 serialize_maps = {'type': 'param_type', 'status': 'param_status'}
# 序列化时自动调用 get_dict_map('param_type') 获取字典映射
# 输出时自动补 data['type_name'] = '系统参数' / '业务参数'
# 输出时自动补 data['status_name'] = '正常' / '禁用'

分页列表和详情接口均自动输出枚举名称，前端可直接展示中文。

按编码取值

这是参数模块的核心自定义方法，供其他业务模块调用：

python

param_service = ParamService()

# 获取参数值（存在且状态=正常时返回值，否则返回默认值）
default_pwd = param_service.get_value_by_code("USER_DEFAULT_PASSWORD", "123456")
upload_limit = param_service.get_value_by_code("UPLOAD_MAX_SIZE", "10")
maintenance = param_service.get_value_by_code("MAINTENANCE_MODE", "0")

实现原理

python

def get_value_by_code(self, code: str, default: Optional[str] = None) -> Optional[str]:
    param = self.repo.get_one(code=code, status=1)  # 按编码查询，状态必须为正常
    return param.value if param else default

repo.get_one(code=code, status=1) 自动过滤软删除记录（is_delete=0）
status=1 确保禁用的参数不会被读取
未找到时返回 default 值，避免调用方判空

典型用法

在其他 service 中注入参数值，实现运行时可调的业务配置：

python

from modules.param.service import param_service

def reset_password(user_id):
    # 从参数表读取默认密码，无需硬编码
    default_pwd = param_service.get_value_by_code("USER_DEFAULT_PASSWORD", "123456")
    # ... 重置密码逻辑

Repository 层

python

class ParamRepository(BaseRepository[Param]):
    """参数数据仓库，继承基础仓库获得通用 CRUD 能力"""
    pass

param_repo = ParamRepository(Param)

参数模块无需自定义查询方法，BaseRepository 的通用方法已满足需求。

API 接口

接口	方法	权限节点	说明
`/api/v1/param/page`	GET	`sys:param:page`	分页查询（支持 name/code 模糊搜索 + type/status 精确匹配）
`/api/v1/param/detail/{id}`	GET	`sys:param:detail`	详情查询
`/api/v1/param/add`	POST	`sys:param:add`	新增参数（自动校验 name/code 唯一性）
`/api/v1/param/update`	PUT	`sys:param:update`	编辑参数（自动校验 name/code 唯一性，排除自身）
`/api/v1/param/delete/{id}`	DELETE	`sys:param:delete`	单条删除
`/api/v1/param/batchDelete`	DELETE	`sys:param:batchDelete`	批量删除

查询参数

分页接口支持以下查询参数（BaseService 自动处理）：

参数	类型	说明
`pageNo`	int	页码，默认 1
`pageSize`	int	每页条数，默认 10
`name`	string	参数名称，模糊搜索
`code`	string	参数编码，模糊搜索
`type`	int	参数类型，精确匹配（0=系统 1=业务）
`status`	int	参数状态，精确匹配（1=正常 2=禁用）

数据字典

参数模块使用以下数据字典（需在字典管理中配置）：

字典编码	用途	字典项示例
`param_type`	参数类型名称	0=系统参数, 1=业务参数
`param_status`	参数状态名称	1=正常, 2=禁用

BaseService 的 serialize_maps 声明后，分页列表和详情接口自动输出 type_name 和 status_name 字段。

与系统配置的区别

特性	参数管理（Param）	系统配置（Config）
用途	单个系统参数	配置分组 + 配置项
结构	扁平（name+code+value）	两级（config + config_item）
典型场景	默认密码、功能开关、上传限制	SMTP 配置、站点信息、第三方服务
取值方式	`param_service.get_value_by_code()`	`config_service.get_value_by_key()`
Service 模式	BaseService 子类	BaseService 子类

开发要点

1. BaseService 子类：声明差异点即可，无需手写 CRUD 逻辑
2. 唯一性校验：unique_fields 声明后自动校验 name 和 code 唯一性
3. 枚举映射：serialize_maps 声明后自动输出 type_name 和 status_name
4. 按编码取值：get_value_by_code() 是核心方法，供其他模块调用
5. 状态值注意：status 使用 1=正常 2=禁用（非 0/1），与文章模块不同
6. 排序规则：page_order_by = (('sort', 'asc'), ('id', 'desc'))，排序号越小越靠前

总结

参数管理模块是项目中典型的 BaseService 简单模块，核心特点：

1. 继承 BaseService：声明 repo/model/page_like_fields/page_eq_fields/unique_fields/serialize_maps 即可
2. 模糊 + 等值搜索：name/code 模糊搜索，type/status 等值搜索，BaseService 自动处理
3. 唯一性校验：name 和 code 双重唯一性，BaseService 自动校验
4. 枚举映射：type 和 status 自动映射为中文名称
5. 按编码取值：get_value_by_code() 供其他业务模块调用，实现运行时可调配置
6. 软删除 + 状态过滤：get_one 自动过滤已删除和已禁用的参数

🔐 认证与安全

📊 数据与配置

📝 日志与监控

🛡️ 防护与治理

📁 文件处理

🔧 核心工具

🧩 辅助工具

模块结构

参数模型

表单验证

Service 层设计

继承 BaseService

差异点详解

page_like_fields（模糊搜索）

page_eq_fields（等值搜索）

page_order_by（排序规则）

unique_fields（唯一性校验）

serialize_maps（枚举显示名映射）

按编码取值

实现原理

Repository 层

API 接口

查询参数

数据字典

与系统配置的区别

开发要点

总结

Become a sponsor

企业级中台解决方案

企业级中台解决方案

模块结构 ​

参数模型 ​

表单验证 ​

Service 层设计 ​

继承 BaseService ​

差异点详解 ​

page_like_fields（模糊搜索） ​

page_eq_fields（等值搜索） ​

page_order_by（排序规则） ​

unique_fields（唯一性校验） ​

serialize_maps（枚举显示名映射） ​

按编码取值 ​

实现原理 ​

Repository 层 ​

API 接口 ​

查询参数 ​

数据字典 ​

与系统配置的区别 ​

开发要点 ​

总结 ​

模块结构

参数模型

表单验证

Service 层设计

继承 BaseService

差异点详解

page_like_fields（模糊搜索）

page_eq_fields（等值搜索）

page_order_by（排序规则）

unique_fields（唯一性校验）

serialize_maps（枚举显示名映射）

按编码取值

实现原理

Repository 层

API 接口

查询参数

数据字典

与系统配置的区别

开发要点

总结