高效BI报表API封装说明提示词

角色定义与任务定位
您应以技术文档架构师的身份进行创作，目标是为开发团队或技术读者生成一份高效、易读、符合行业标准的BI报表API封装说明。这份说明需要覆盖认证、请求/响应格式、分页、错误码等核心环节，并辅以清晰的流程图或序列图，确保开发者能直接参照实现集成。请围绕“高效”与“封装”两个关键词，重点突出接口的简洁性、复用性和可维护性。

适用场景

内部开发团队快速编写API接入文档
对外发布的BI产品技术博客或SDK指南
产品集成手册中关于报表数据查询接口的封装说明
技术方案评审时用作参考文档


核心提示词
以下提示词可直接复制用于AI文本生成或视觉设计辅助：

“请以专业技术文档风格，编写一份BI报表API的封装说明。包含以下模块：接口概述、认证方式（API Key/OAuth2）、请求URL与HTTP方法、请求参数表（含名称、类型、必填、默认值、说明）、响应JSON结构示例、分页说明、常见错误码及含义。语言简洁，避免多余修饰，分点或表格呈现。使用伪代码或Python/JavaScript示例展示核心调用逻辑。”
“为上述封装说明生成一张序列图，展示客户端通过封装层请求BI报表数据的过程：客户端调用封装函数→封装层拼接参数→发送HTTPS请求→服务端返回数据→封装层解析并返回结构化对象。标注关键步骤耗时与错误处理分支。”
“用流程图展示API封装的内部逻辑：输入校验→构建请求头→设置超时重试机制→调用HTTP客户端→解析响应→抛出业务异常或返回数据模型。”


风格方向

专业严谨：使用标准术语，如“RESTful”、“payload”、“请求签名”、“限流策略”。
简约清晰：每段说明不超过3个要点，避免长段落；代码示例使用等宽字体风格（视觉上建议灰底白字或深色代码块）。
层次分明：采用“一级标题—二级标题—表格/列表”结构，符合开发者阅读习惯。
视觉辅助：流程图使用统一颜色（蓝色表示请求，绿色表示成功，红色表示错误），线条简洁。


构图建议
若需为封装说明配图（用于页面展示或培训材料）：

流程图：从“客户端调用”到“返回数据”共5个方框，箭头标注“验证→构造→发送→解析→返回”，底部附加错误回调分支。
表格布局：参数表建议左对齐，表头加粗，用浅灰交替行背景，方便快速扫描。
分页说明图：展示“page_size”和“page_token”两个关键参数如何改变请求URL，并标注下一页的指示返回。
色彩原则：主色调使用科技蓝（#007BFF）与深灰（#333），强调部分用橙色（#FF6B00）标注注意事项。


细节强化

在API认证部分加入“密钥轮换策略”与“安全传输建议（HTTPS+TLS 1.3）”。
在响应结构中加入“元数据字段（total_count, next_token）”说明，体现高效分页。
在错误码表里包含“429 Too Many Requests”以及对应的指数退避重试方案。
代码示例中展示“封装函数签名”如 def get_report(api_key, report_id, page_size=100, page_token=None)，并注明异常类型。
补充性能优化提示：连接池复用、gzip压缩、本地缓存维度元数据。


使用建议

将上述“核心提示词”直接输入AI文本生成工具（如GPT、Claude），配合风格方向中的描述可得到初稿，再针对实际BI产品调整参数名和示例值。
如需生成配套流程图，可使用Mermaid语法或Draw.io的AI生成功能，引用本文“构图建议”中的节点描述。
最终文档建议导出为PDF或嵌入到API门户（如Swagger UI的“描述”字段），并在每段前添加可折叠代码块提升阅读体验。
若用于视觉设计，可将“核心提示词”中的代码示例以高亮形式排列，配以注释气泡，形成可读性极强的图文说明。