用途:在 API 设计第一步,把业务对象抽象为可寻址的 REST 资源,决定资源粒度与关系。不适用于 RPC 风格 API 和 GraphQL(后者用 schema 建模)。
核心原则:资源是名词而非动词(用 /users 而非 /createUser);粒度适中;资源对应业务对象而非照搬数据库表;通过路径表达从属关系,如 /users/123/orders。
四种资源模式:集合 /resources(GET 查询列表、POST 创建);单资源 /resources/{id}(GET、PUT、PATCH、DELETE);子资源 /resources/{id}/sub-resources(如 /users/123/orders);动作端点 /resources/{id}/actions/{action}(如 POST /orders/123/cancel)。
命名规范:复数、小写加连字符、名词;避免单数、驼峰、动词。
工作流程:列出业务对象,判断顶层资源与子资源,梳理关系,命名资源,识别动作端点场景,画 ER 图,输出端点清单,再转交 endpoint-design 设计具体端点。
质量自检:资源为名词、复数一致、小写连字符、子资源确实不独立、嵌套不超过 3 层、动作端点无法用 CRUD 表达、ER 图完整。
常见坑:照搬数据库表、资源用动词、嵌套过深、强行用 CRUD 改状态、子资源独立化、命名混乱。
配套模板:templates/resource-model-template.md。上游可参考 product-manager 的业务实体清单与 database-engineer 的实体关系;下游衔接 endpoint-design 与 request-response。