数据分析API封装说明结构化提示词

角色定义与任务定位
请以资深后端开发工程师兼技术文档架构师的身份进行创作。你的核心目标是：为开发团队或API使用者，撰写一份逻辑严谨、步骤清晰、可直接指导编码实践的数据分析API封装说明。这份文档需阐明封装的价值、设计思路、具体实现流程及最佳实践，而非简单的功能罗列。
适用场景

为内部数据分析服务构建统一、安全的API网关层。
将复杂的多数据源查询与处理逻辑抽象为简易的API接口。
编写面向第三方开发者的数据分析能力开放平台接口文档。
重构或优化现有分散的数据接口，实现标准化输出与集中管理。

核心提示词
以下提示词可直接组合或单独使用，作为文档各章节的核心内容引导：

封装目标阐述：统一数据访问入口、简化调用复杂度、保障数据安全与一致性、提升接口性能与可维护性。
核心流程拆解：1. 数据源配置与连接池管理 -> 2. 输入参数验证与标准化 -> 3. 业务逻辑调度与计算引擎调用 -> 4. 结果集格式化与缓存处理 -> 5. 统一响应结构与异常返回。
接口设计要点：遵循RESTful规范；设计清晰的资源路径（如 `/api/v1/analysis/sales-trend`）；定义强类型的请求/响应模型（JSON Schema）；包含分页、过滤、时间范围等通用参数。
关键代码示例：提供核心封装类的伪代码或特定语言（如Python/Java）的代码片段，展示如何初始化客户端、发送请求、处理响应及错误。

风格方向

文体风格：采用技术手册的客观、精准风格，避免口语化和营销语气。以“说明”和“指导”为核心，而非“宣传”。
叙述逻辑：采用“总-分-总”结构：先概述封装价值与整体架构，再分模块详述设计细节与实现步骤，最后总结最佳实践与注意事项。
术语使用：准确使用“接口抽象”、“负载均衡”、“降级策略”、“序列化”、“鉴权机制”等专业术语，并确保上下文中有简明解释。

构图建议（文档结构）

顶层框架：文档标题 -> 版本与修订历史 -> 概述（目标与读者） -> 快速开始。
主体内容层：架构设计图（可文字描述MVC或分层架构） -> API接口详细说明（按功能模块分组） -> 请求/响应示例 -> 错误代码列表。
细节深入层：封装的具体实现步骤（代码目录结构、核心类说明） -> 配置项详解 -> 性能优化建议 -> 安全注意事项。
附录层：常见问题解答（FAQ）、术语表、相关资源链接。

细节强化

强调非功能性需求：在说明中融入对“并发处理”、“响应时长”、“数据缓存策略”、“限流与熔断”的考量点。
可视化辅助：用文字引导绘制或描述“数据流转时序图”或“系统上下文图”，明确数据从原始库到API输出的关键节点。
对比呈现：可简要对比封装前（直接访问数据库/多个分散接口）与封装后（统一API调用）在调用方式、安全性和维护成本上的差异。
实战检查点：提示文档应包含“如何添加一个新的数据分析指标”、“如何进行接口版本升级”等实际开发中会遇到的操作指南。

使用建议

将“核心提示词”中的条目作为文档大纲的一级或二级标题，并展开撰写。
在“风格方向”指导下，确保全文语气一致、逻辑递进，避免在不同章节跳跃于概述与细节之间。
利用“构图建议”搭建完整的文档骨架，再根据具体API的复杂程度，选择“细节强化”中的要点进行深入填充。
最终产出应是一份可直接交付给开发团队或用户的、具备可执行性的技术说明文档。