进阶版后端接口技术方案写作提示词

角色定义

你是一名资深后端架构师兼技术方案撰写专家。你的任务是为后端接口技术方案提供结构化、可落地的写作框架，确保方案具备清晰的逻辑层次、完整的接口定义、严谨的数据约束以及可读性强的表达。请以“让评审者一目了然、让开发者直接上手”为目标，输出可直接用于文档编写的提示词内容。

适用场景

• 后端接口设计评审与方案汇报
• 微服务/单体架构中RESTful或gRPC接口文档输出
• 第三方对接、开放平台API规范编写
• 技术方案模板标准化与团队协作
• 前后端联调、接口版本迭代说明

核心提示词

以下提示词可直接复制并填入具体业务场景中使用：

• “请以RESTful风格设计一套用户管理接口，包含注册、登录、信息查询、权限修改四个端点。每个端点需明确请求方法、路径、请求头、请求体JSON字段（含类型、必填、示例值）、成功/失败响应结构、HTTP状态码、错误码列表及说明，并补充限流策略与幂等性保障。”
• “围绕订单系统的核心接口，编写包含接入说明、鉴权方式（Token/OAuth2）、通用错误码、分页参数规范、字段校验规则（如枚举值范围、字符串长度）的技术方案草案。每项接口都要给出CURL示例和典型返回报文，并标注版本号。”
• “针对异步任务处理场景，设计回调接口规范。内容需包括回调触发条件、签名验签方法、重试机制、超时阈值、回调日志记录的约束要求，以及异常情况下的降级策略说明。”

风格方向

• 专业严谨：使用标准术语（如HTTP/1.1、REST、幂等性），避免口语化表达。
• 简洁可操作：每段描述不超过三句话，重点用列表或表格（在提示词中可建议用列表呈现）。
• 结构层次分明：按“概述→接口定义→数据模型→安全→错误处理→性能要求”顺序组织。
• 面向读者：兼顾前端开发、测试、运维、产品等多角色阅读体验。

构图建议（文档结构）

将以下结构作为技术方案的骨架，按顺序组织内容：

• 概述：说明接口背景、用途、涉及系统、阅读对象。
• 接口清单：以表格形式列出所有端点、方法、简要功能。
• 详细接口描述：每个接口独立小节，包含请求参数表、响应参数表、错误码表、示例。
• 数据模型定义：公共实体字段说明、枚举常量、枚举含义。
• 安全与鉴权：认证流程、Token有效期、签名算法、IP白名单等。
• 错误处理与异常：全局错误码分类、业务异常返回格式、降级方案。
• 性能与约束：QPS限制、数据大小限制、超时配置、缓存策略。

细节强化

• 字段约束：明确每个字段的“必填/可选”、“数据类型”、“长度/取值范围”、“默认值”。
• 状态码语义：200表示成功，400参数错误，401未授权，403无权限，404资源不存在，500系统异常；避免滥用200。
• 幂等性声明：对POST/PATCH等非幂等方法给出唯一请求号（idempotency-key）机制。
• 版本管理：在URL路径中加入版本号（如/v1/），并在响应头中携带版本标识。
• 日志与追踪：要求每个请求附带traceId，并说明日志记录字段与保留周期。

使用建议

• 将上述核心提示词直接输入给AI助手（如ChatGPT、Claude）或复制到文档模板中，即可获得结构化的方案初稿。
• 编写过程中保持“接口即契约”思维：每个字段都要有明确语义，避免歧义。
• 完成后请立即请一名后端和一名前端工程师进行交叉审阅，确保实现可行性。
• 建议配合Swagger/OpenAPI工具生成可交互文档，与提示词内容互补。
• 若涉及敏感信息（如密钥、内网地址），在示例中用占位符（如{API_KEY}）替代。