模型与接口设计 · Arkk 的笔记

用于新增或修改持久状态、状态流转、跨模块接口。只展开变化涉及的模型和契约，已有 Schema、OpenAPI 或 Protobuf 定义直接引用。

状态归属与数据约束

明确关键状态的权威来源、写入者和冲突裁决方式。权威来源是逻辑归属，不要求仅一份物理副本。派生视图、缓存和副本说明更新机制、可接受滞后与恢复方式。

持久化设计检查主键、唯一约束、可空性、关联和删除行为；是否使用外键取决于存储能力与完整性责任，不要求每个模型都有聚合根。依据查询形态选择索引，以执行计划和代表性数据验证；小表扫描并非天然错误。

涉及流程时，从业务完成与结束条件推导允许的状态迁移、触发者和可观察依据。受理请求、执行副作用和确认结果可能发生在不同时间；只区分真实存在的差异，不给同步无副作用操作增加状态机。

异步操作还要明确取消请求何时生效、在途动作由谁跟踪、何时可以清除记录或结束恢复责任。一次状态快照或本地标志不能单独证明外部动作已经终结；交错风险用韧性与并发防御检查。

选项：现有输入无法表达真实使用差异时才新增参数或模式。
默认行为：遵循约定的任务范围，业务筛选须有依据。例如按路径查询记录，默认扫描该路径，不因目录名为 archive 就隐藏内容。
数据格式：明确输入输出、必填与可选、分页及大小限制；结构服从语义。
结果语义：响应表示受理、完成还是等待核实？取消是已接受请求还是已确认终结？调用方据此采取什么动作，须与状态及可观察证据一致。
明确鉴权和资源归属检查，不把客户端校验当作安全边界。
错误区分参数问题、权限问题、业务拒绝、暂时不可用和结果未知。例如 INVALID_PARAM 不应原样重试，限流应遵循退避提示；是否安全重试还取决于操作防重能力。
有重复副作用风险的写操作明确防重范围与有效期，可采用业务唯一键、条件更新或幂等键，不要求每个写接口新增字段。

例如支付幂等键需要约定用户范围、同键不同参数如何拒绝、处理中如何返回和结果保存多久。只声明“支持幂等”不足以指导实现与验证。

模型或接口变化检查老数据与调用方兼容；重要业务语义变化先确认，内部表示调整由工程自行判断。