开源coze源码系列之API结构

健康生活 2025年09月07日 14:50 1 admin

Coze Studio后端采用了一套全面的API架构，旨在实现灵活性、高性能和开发者易用性。本文档探讨了API的结构、组织及其关键组件，以帮助您有效导航和与系统交互。

Coze Studio的API基于分层架构，使用Hertz网络框架构建，这是一个适用于Go语言的高性能HTTP框架。API遵循层次组织模式，不同功能域之间有明确的关注点分离。

API围绕核心业务域组织，端点按功能分组，公网API和内部API之间有明确的分隔。、

来源：register.go#L34-L38

API路由组织

Coze Studio的API路由遵循层次结构，包含几个顶层组：

API基础路径	描述	版本
/api/*	核心内部API端点	当前
/v1/*	与OpenAPI兼容的RESTful端点	稳定
/v3/*	最新一代端点	最新

每个API组包含特定领域的子组，封装了相关功能。这种组织方式使API更易于发现，并保持了关注点的清晰分离。

来源：api.go#L19-L451

核心API组

Coze Studio的主要功能组织成以下API组：

每个组处理系统内的特定功能域：

对话APIs (/api/conversation)：管理聊天交互、消息和对话历史
知识APIs (/api/knowledge)：处理知识库、文档和数据检索
内存APIs (/api/memory)：管理数据库连接和变量存储
插件APIs (/api/plugin_api)：集成和管理外部插件和API
工作流APIs (/api/workflow_api)：创建、执行和管理代理工作流

来源：api.go#L37-L43, api.go#L94-L136

HTTP方法和请求模式

Coze Studio的API主要使用两种HTTP方法：

POST：用于大多数操作，包括数据创建、更新和复杂查询
GET：用于简单的数据检索操作

API端点通常遵循以下命名模式：

模式	示例	目的
创建/添加	/api/knowledge/create	创建新资源
获取/列表	/api/memory/database/list	检索资源
更新	/api/workflow_api/update_meta	修改现有资源
删除	/api/knowledge/document/delete	删除资源
动作动词	/api/workflow_api/publish	执行特定操作

认证和授权

API包含几种认证机制：

基于会话的认证，适用于网页界面用户
个人访问令牌（PAT），用于API集成
OAuth，用于第三方集成

这些通过中间件实现，在请求到达处理器之前进行处理：

与认证相关的端点主要位于/api/passport和/api/permission_api组中。

来源：middleware/openapi_auth.go, api.go#L211-L222, api.go#L252-L260

OpenAPI兼容端点

对于公网API访问，Coze Studio在/v1路径下提供OpenAPI兼容端点：

/v1/conversations - 管理对话

/v1/conversation/:id - 操作特定对话

/v1/workflow - 运行和管理工作流

/v1/files - 处理文件上传

这些端点遵循更标准的RESTful约定，专为外部集成设计。

来源：api.go#L410-L447

核心功能APIs

对话管理

对话APIs处理聊天交互和消息管理：

端点	目的
/api/conversation/chat	启动代理对话
/api/conversation/get_message_list	检索消息历史
/api/conversation/clear_message	清除对话历史
/api/conversation/delete_message	删除特定消息

来源：api.go#L37-L43

知识库

知识APIs管理文档存储和检索：

端点	目的
/api/knowledge/create	创建知识数据集
/api/knowledge/document/create	向知识库添加文档
/api/knowledge/document/list	列出可用文档
/api/knowledge/slice/list	管理文档片段

来源：api.go#L94-L136

工作流系统

工作流APIs支持创建和执行代理工作流：

端点	目的
/api/workflow_api/create	创建新工作流
/api/workflow_api/save	保存工作流更改
/api/workflow_api/test_run	测试工作流执行
/api/workflow_api/publish	发布工作流以供使用
/api/workflow_api/node_type	查询可用节点类型

来源：api.go#L355-L390

插件系统

插件APIs处理外部工具的集成和管理：

端点	目的
/api/plugin_api/register	注册新插件
/api/plugin_api/create_api	创建API定义
/api/plugin_api/debug_api	调试插件API
/api/plugin_api/publish_plugin	发布插件

来源：api.go#L301-L334

错误处理

API通过一致的响应格式实现标准化错误处理：

错误响应包括：

HTTP状态码
内部错误码
描述性错误消息
可选的上下文数据

来源：internal/httputil/error_resp.go

API实现

API端点作为处理器实现在backend/api/handler/coze目录中。每个处理器遵循一致的模式：

请求验证
参数提取
业务逻辑执行
响应格式化

处理器与应用层和领域层交互以执行业务逻辑，同时保持关注点分离。

来源：handler/coze/base.go

API中间件

API使用多个中间件组件处理横切关注点：

中间件	目的
会话	管理用户会话
日志	记录API访问和错误
上下文缓存	优化请求性能
认证	验证用户身份
国际化	处理国际化