用途:在 API 端点的请求与响应结构设计阶段使用,也适用于字段定义、校验规则编写、响应格式与字段命名规范制定。
主要能力与原则:字段稳定性——公开字段发布后不轻易改语义,能扩展不能删;字段含义清晰,命名见名知意;全 API 命名风格一致(snake_case 或 camelCase 二选一);默认不返回密码哈希、内部 ID、调试信息等敏感内容。
请求结构:Path 参数标识资源(如 GET /users/{user_id}/orders/{order_id});Query 参数用于筛选、分页与选项(如 page、page_size、status、sort,sort 前缀 - 表示倒序);Header 承载横切信息(Authorization、Content-Type、Accept、Idempotency-Key、X-Request-Id、If-Match、Accept-Language);Body 用于创建或修改数据。每个字段需定义类型、必填/可选、长度与范围限制、格式(email/url/uuid/date/regex)、枚举值、默认值及跨字段规则,可参照 OpenAPI 校验写法。
响应结构:单资源直接返回字段对象;列表推荐用 data 加 pagination(page、page_size、total、total_pages)结构;嵌套避免过深,超过 3 层改用 ID 加单独 GET。命名规范:风格选定后坚持;ID 用前缀化(如 usr_abc123)或纯 UUID;时间统一 ISO 8601 + UTC;布尔用 is/has 前缀;枚举用字符串。
工作流程:读取端点清单,逐个定义请求结构、字段校验、成功与失败响应,检查命名一致性与时间/布尔/枚举规范后输出说明。质量自检涵盖命名一致、时间格式、布尔值、枚举、必填标注、校验完整性、敏感字段、列表分页与嵌套层数。
限制与配套:需与 endpoint-design、resource-modeling 等上游技能及 error-handling、pagination-filtering、openapi-mock 协作;配套模板为 templates/request-response-template.md,参考 references/request-response-guide.md。具体工具链与运行方式暂未提供。