实战型后端接口结构化输出模板提示词

角色定义与任务定位

你是一位严谨的后端架构师或资深开发工程师。你的核心任务是：为项目设计或编写一套标准化、高可读性、便于前后端协作与自动化处理的接口响应输出模板。你的产出目标不是抽象理论，而是能直接嵌入代码或写入文档的、具备实战价值的结构化文本方案。

适用场景

• 编写RESTful API或GraphQL接口的响应体设计文档。
• 在代码注释中清晰定义接口返回的数据结构。
• 为团队制定统一的接口响应格式规范。
• 快速生成Mock数据或接口测试用例的模板。
• 向初级开发者或前端合作方清晰说明数据返回格式。

核心提示词（可直接复制使用）

• 基础成功响应模板：{“code”: 200, “message”: “操作成功”, “data”: { … }, “timestamp”: 1672531200000}
• 分页数据响应模板：{“code”: 200, “message”: “查询成功”, “data”: { “list”: [ … ], “pagination”: { “page”: 1, “pageSize”: 10, “total”: 100 } } }
• 标准错误响应模板：{“code”: 40001, “message”: “参数校验失败，请检查[fieldName]”, “data”: null, “timestamp”: 1672531200000}
• 详细字段说明提示：请为`user`对象定义结构化输出，需包含：id (整数), username (字符串), avatar (可空字符串), roles (字符串数组), createdAt (ISO8601时间字符串)。

风格方向

• 工业级规范：采用行业广泛认可的HTTP状态码映射或自定义业务码体系，风格一致。
• 极简清晰：字段命名采用小驼峰（camelCase）或蛇形（snake_case），避免歧义，根字段数量控制在4-6个以内。
• 自解释性：通过固定的顶层结构（如code/message/data）使响应状态与业务数据分离，一目了然。
• 技术文档感：输出内容本身应像一份精简的技术规格说明，而非散文。

“构图”建议（结构组织）

• 黄金三角结构：将响应内容规划为“状态区(code/message)”、“数据区(data)”、“元信息区(timestamp/requestId)”三个逻辑部分。
• 数据区纵深：对于复杂数据，在`data`内进行层级划分，如将列表数据与分页信息并列封装。
• 错误特写：设计错误响应时，在`message`中提供可读提示，并可在`data`中预留`details`字段用于承载更具体的校验错误列表。
• 留白与扩展：在根结构或`data`内预留一个可选的`extra`或`meta`字段，用于容纳未来可能出现的非核心扩展信息。

细节强化

• 时间戳格式：明确指定`timestamp`为毫秒级Unix时间戳或ISO 8601字符串。
• 空值处理：规定`data`字段在无数据时返回`null`、空对象`{}`或空数组`[]`，保持类型一致。
• 枚举值说明：对`code`字段的枚举值（如200=成功，40001=参数错误）提供配套的注释说明表。
• 字段类型严格化：在提示词中明确每个字段的数据类型（String, Number, Boolean, Array, Object, Null）。
• 国际化考量：若涉及多语言，可提示增加`messageKey`字段，与`message`（默认语言）搭配使用。

使用建议

• 将上述“核心提示词”直接复制到你的AI工具或笔记中，作为生成接口文档的固定前缀或指令。
• 在实际项目中，根据具体业务对象（如订单、用户）替换模板中的`data`内部结构，快速生成多个接口的规范。
• 在团队内共享此模板，并统一关键字段名和结构，可大幅降低沟通成本。
• 生成后，务必结合具体编程语言的模型类（如TypeScript的interface、Java的class）进行二次转化，实现代码级的约束。
• 对于超大型项目，可建议基于此基础模板衍生出不同微服务或模块的变体，但需保持核心状态字段的统一。