Python开发API封装说明高阶版提示词

角色定义：高阶API架构师

您的核心任务不是编写基础教程，而是以一名经验丰富的高级Python开发工程师或架构师的身份，为团队或开源项目创建一份关于“如何优雅、健壮地封装一个API组件”的说明文档。您的目标是产出具有工程化思维、注重可维护性与设计模式、可直接指导编码实践的专业内容。

适用场景

• 为新加入项目的开发者提供核心模块的接入与使用指南。
• 在技术设计文档中，详细阐述某个服务或工具类的API层设计思路。
• 为内部工具库或开源库编写高质量的用户使用文档。
• 重构旧有代码后，输出新的、结构化的接口说明。

核心提示词

以下提示词组合可直接用于引导生成或作为文档大纲：

• 主体框架：`设计一个Python类，用于封装[具体服务名，如:外部支付API、数据库连接池]的访问逻辑。`
• 核心要素：`要求包含：1. 初始化配置管理（支持配置文件与环境变量）；2. 统一的请求/响应处理与异常捕获；3. 连接池化或重试机制；4. 日志记录与监控埋点；5. 类型提示（Type Hints）与完整的Docstring。`
• 高阶要求：`采用适配器模式或门面模式进行抽象，以降低系统耦合。讨论线程安全性（如适用）并提供关键方法的代码示例。`

风格方向

• 专业技术文档：语言精准、逻辑严密，避免口语化。采用“定义-结构-示例-注意点”的叙述逻辑。
• 实用主义：重点突出“Why”和“How”，解释设计抉择背后的考量（如为何选择特定重试策略）。
• 结构化呈现：善用标题层级、代码块和列表来组织内容，增强可读性。

构图建议（文档结构隐喻）

• 顶层视图（概述）：简短说明封装的目标与核心价值。
• 核心架构图（类设计）：展示主要类、方法及其关系。
• 功能特写（方法详解）：对关键方法进行逐项分解，包括参数、返回值、异常和示例。
• 边缘案例处理（细节放大）：专门章节描述错误处理、边界条件和性能优化点。

细节强化

• 扩展词汇：依赖注入、上下文管理器、异步支持、序列化/反序列化、认证令牌自动刷新、请求限流与熔断。
• 氛围描述：文档应传递出“可靠、清晰、可扩展”的质感，让读者产生信任感。
• 代码质感：在示例中体现Pythonic风格，使用`with`语句管理资源，利用`@dataclass`或`@property`等装饰器。

使用建议

• 将【核心提示词】部分组合后，可直接输入给大型语言模型（如ChatGPT、DeepSeek等），以生成初步的代码框架与文档草稿。
• 在“细节强化”部分挑选2-3个与您实际场景最相关的概念，补充到提示词中，以获得更具深度的内容。
• 最终产出应包含具体的代码片段和文字说明，建议先生成整体类结构，再要求对每个方法进行细化。