高阶版后端接口API集成说明提示词

角色定义与任务定位

请以“资深后端架构师兼技术布道师”的身份，为你的开发团队或合作伙伴撰写一份API集成说明。你的核心目标是：生成一份超越基础功能罗列、具备架构洞察、最佳实践指导和行业应用场景解构的高阶技术文档，旨在提升集成效率、保障系统稳定并阐明商业价值。

适用场景

• 向第三方合作伙伴提供核心业务能力的集成文档。
• 在大型微服务架构中，为内部其他团队提供标准化服务接口说明。
• 为具有复杂业务逻辑、高安全要求或高性能需求的企业级API编写技术白皮书的一部分。
• 作为售前技术方案中的关键交付件，展示技术实力与可靠性。

核心提示词

可直接组合使用的提示词示例：

• 撰写一份关于[支付风控API]的集成说明，重点阐述其基于实时行为分析的决策引擎架构、与现有支付流程的钩子集成点、以及如何在电商反欺诈行业场景中配置不同风险阈值。
• 生成[用户画像数据同步API]的高阶说明文档，需包含增量同步与全量同步的混合策略、数据一致性保障的Saga事务模式图解、以及在精准营销和个性化推荐两个典型应用中的数据结构映射示例。
• 编写[物联网设备指令下发API]的集成指南，核心需说明海量并发连接下的长连接管理方案、指令优先级队列与重试机制、以及在智慧物流行业中对设备状态回执的异步处理流程。

风格方向

• 专业严谨：采用技术文档的客观语气，避免口语化，术语准确。
• 结构化清晰：文档具备清晰的层级（概述、认证、接口详情、错误码、示例、FAQ）。
• 价值导向：在技术描述中，适时点明该设计或功能所能解决的业务痛点或带来的效率提升。
• 图文并茂导向：为关键流程（如鉴权流程、数据流、状态机）预留图表说明位置。

构图建议（文档视觉结构）

• 顶层架构图：展示API在整体业务系统中的位置及上下游依赖。
• 核心交互时序图：清晰描绘一次完整API调用的关键步骤与组件交互。
• 状态迁移图：适用于描述订单、任务等有状态变化的API。
• 数据模型关系图：阐明请求/响应参数中复杂对象的结构与关联。
• 代码块高亮：使用等宽字体，对请求示例、响应示例、关键代码片段进行突出展示。

细节强化

• 认证与安全：详细说明OAuth 2.0、JWT、API Key等机制的具体使用方式、签名算法示例和Token刷新策略。
• 限流与熔断：明确QPS限制、并发数、熔断策略（如Sentinel/Hystrix配置参考）及超出限制后的友好提示。
• 幂等性保障：解释幂等性设计，并提供通过唯一请求ID实现幂等的具体方案。
• 监控与观测：建议集成方关注的监控指标（如延迟、成功率），并给出与Prometheus、SkyWalking等集成的日志与链路追踪标识。
• 版本管理：说明API版本迭代策略、废弃时间表及向后兼容性承诺。

使用建议

• 将“核心提示词”中的括号内容替换为您的具体API名称和行业，即可生成初稿框架。
• 在“细节强化”部分选择与您的API最相关的3-4个点进行深入展开，避免面面俱到但深度不足。
• “构图建议”中的图表，可使用Mermaid、PlantUML等工具生成，或提示AI辅助描述图表内容后再由人工绘制。
• 最终文档应包含一个“快速开始”章节，让开发者能在5分钟内完成第一次成功调用，再逐步深入高阶内容。