API 通用模板

摘要

本文档定义了一套适用于特定系统的 API 请求与响应的通用结构规范。它详细描述了通用请求头、请求 Cookies、响应头和标准响应体的格式，旨在为开发者提供清晰、一致的接口对接范式。标准响应体通过 code、message、data 和 error 四个字段来结构化返回信息，便于统一处理成功或失败的业务逻辑。

核心要点

• 定义了通用的请求头（通用请求头）和请求 Cookies（通用请求 Cookies）结构。
• 定义了通用的响应头（通用响应头）和标准响应体（通用响应体）结构。
• 标准响应体采用统一的 JSON 结构：包含 `code`（状态码）、`message`（消息）、`data`（数据主体）和 `error`（错误详情）四个核心字段。
• 响应体中的 `data` 字段内容根据具体接口的业务逻辑而变化，文档提供了添加内容接口作为范例。
• 文档开头有注释表明此模板可能非必需，暗示系统或已有更好的解决方案。

关键实体

• API (concept)

相关内容

• [[开发规范备忘docx处理与argparse安全访问.md]]

建议新建页面

• [[RESTful API 设计模式]] — 原文是特定系统的通用模板，一个更通用的关于 RESTful API 设计原则、状态码使用、资源命名等的独立页面将具有更广泛的参考价值。
• [[API 身份验证机制]] — 文中提到了 Bearer Token 鉴权，但未展开。一个独立页面可以系统介绍 OAuth、JWT、API Key 等常见认证方式及其安全实践。
• [[API 错误处理与状态码规范]] — 原文展示了 code 和 error 字段，一个独立页面可以深入探讨如何设计和维护一致的错误代码体系、错误消息国际化、以及客户端的最佳处理策略。

---

> 编译时间: 2026-06-12 04:39 | 来源: `zblog-docs/api-15-common-template.md`