用途:用于搭建新的 API/后端功能、将代码重构为清晰的分层结构、强化关注点分离。
主要能力:规定 route→controller→service→repository 的调用流,各层职责严格不重叠。每个功能是一个独立文件夹,包含 schemas(校验)、types(TypeScript 类型/接口)、config(常量)、utils 或 helpers(纯函数)、crons(定时任务)、index.ts(统一导出)。目录按功能而非按层分组。
用法要点:路由只定义 RESTful 端点,不含逻辑;控制器处理 req/res、校验输入、用 jsDoc 标注路由;服务承载业务逻辑且与 HTTP 无关;仓储只做数据库操作,类以 export default 导出(不是实例),构造函数注入模型,且只能在 src/shared/db/repositories.ts 中实例化一次。仓储文件放在 packages/cx-datastore/src/repositories/<domain>/。目录名一律用复数(controllers/、services/ 等),文件名用 snake_case,模型文件例外用 PascalCase。每个模块的 index.ts 只按名导出对外所需内容,禁止 export *;跨模块引用必须走 index.ts,模块内部用相对路径。service→util/helper 允许,反向禁止。cron 只能引用 repository 与 helper/util。
适用场景:需要清晰分层与模块化的后端代码库,尤其是使用 Sequelize 模型、需要跨包共享仓储的项目。可与 cx-tdd、cx-improve-architecture、cx-domain-model 配合。
限制与反模式:控制器不应内嵌逻辑、服务不应触碰 req/res、仓储不应含业务规则、仓储不得放在 src/modules/ 内、cron 不得调用 service/controller。资料中不涉及安装命令、收费、价格或具体平台版本等信息。