用途:为 TypeScript 项目决定何时使用函数式模式(字面量联合、可辨识联合、brand、Option、Result 等),核心原则是选择性使用,而非默认架构或额外抽象层。
边界优先顺序:先复用所属边界的现有 schema、生成类型、库类型或公共契约;再用已安装工具支持的推断工具推导类型;然后组合、细化或扩展规范 schema;只有当任务暴露真实缺口时才在归属处改进表示;最后仅当满足硬性门槛才引入一个最小自定义类型。一旦现有表示能安全表达需求就停止。
规范归属:TypeBox schema 负责请求与响应形状,用 Static<typeof Schema> 及组合;Drizzle 表负责持久化形状,用 typeof table.$inferSelect、typeof table.$inferInsert;DynamoDB Toolbox 实体负责条目形状,用 InputItem<typeof Entity>、FormattedItem<typeof Entity>;Effect Schema 等已装库负责其推断类型、细化与解析错误;项目已有的可空、抛错、Promise、生成式或普通 TypeScript 契约保持规范地位。
职责划分:领域模型负责构造、保持不变量的转换与类型化解码;仓储负责 I/O、查询、事务与驱动错误分类;服务负责用例编排;路由负责 HTTP 校验与响应序列化。纯不变量函数保持纯,不对整个 domain 目录强加导入纯度规则。领域模型不得导入 Fastify 处理器、数据库客户端、DynamoDB 命令、SQL 构建器、Layer、运行时执行、配置或环境访问。
不要添加中间模型:不merek为改字段名或重复校验而在 API schema 与持久化 schema 之间放手写可辨识、brand 或基于类的模型。不同边界可有不同类型,无需第三个通用领域类型连接。
自定义类型硬性门槛(须全部满足):改动代码存在具体缺陷、无效状态或不安全交换;所属 schema、已装库与现有类型无法通过组合、细化、字面量、约束或原生错误模型表达;新类型能阻止缺陷而非复述校验;单一边界能一致地负责构造与校验;不引入例程适配器、重复序列化器或第二表示。任一不满足则保留现有表示。
选最小表示:优先字面量联合如 "pending" | "settled";变体携带不同数据或能消除无效字段组合时用可辨识联合;同原始表示易混淆时才用 brand;先考虑既有可空或失败契约再考虑 Option 或 Result。运行时校验保留在所属 schema,自定义编译期类型不得替代边界校验。
方法:检查导入、依赖、schema、生成类型、公共契约与直接调用方;命名具体不安全状态;复用或扩展能阻止它的最高归属者;用包内现有测试工具验证改动行为。参考 ADT、Option/Result、brand、迁移指南等仅读与当前问题相关部分。限制:具体命令与代码示例资料暂未提供。