快速开始
本指南用一条最短路径完成：登录 → 选择项目 → 接入数据源 → 开发接口 → 测试 → 发布 → 创建凭证 → 授权 → 调用。每一步都对应产品中的真实菜单。
1. 登录并选择项目
打开前端地址（本地为 http://localhost:7001），使用管理员分配的账号登录。
新建项目需要填写：
| 字段 | 说明 |
|---|---|
| 项目名称 | 用于项目切换器展示 |
| 接口前缀 | 全平台唯一，比较时忽略大小写与首尾斜杠 |
| 项目描述 | 可选 |
项目创建后会自动初始化 dev 开发环境与生产环境，并绑定默认执行服务。
2. 接入数据源
进入【数据源】，点击新建并选择类型，填写连接信息后先 测试连接 再保存。
- 选择数据源类型，例如 MySQL、PostgreSQL、达梦、ElasticSearch。
- 填写地址、端口、库名、账号与密码。
- 按需配置连接池；留空时使用平台默认值。
- 保存后可展开元数据树，浏览 Schema、表、字段，并在只读查询页预览数据。
支持 11 种 SQL 数据源与 5 种 NoSQL / 新型数据源，详见 数据源管理。
3. 创建第一个接口
进入【工作台】，点击一种开发模式：
| 模式 | 适合场景 |
|---|---|
| 脚本模式 | 需要手写 SQL、动态条件、批量操作 |
| 单表模式 | 单表查询，零代码勾选字段 |
| 代理模式 | 包装第三方 HTTP 接口 |
| 编排模式 | 聚合多个已发布接口并做数据处理 |
以脚本模式为例：
- 选择数据源与 Schema。
- 编写 SQL，支持
#{}预编译参数与<if>等动态标签。
SELECT id, order_no, amount, status, created_at
FROM orders
WHERE 1 = 1
<if test="status != null">
AND status = #{status}
</if>
<if test="startTime != null">
AND created_at >= #{startTime}
</if>
ORDER BY created_at DESC
- 点击【解析】自动提取请求参数与返回字段，也可以手动补充。
- 在右侧面板填写接口名称、接口地址、请求方式、认证方式等基本信息。
接口定义的完整字段说明见 接口定义。
4. 在线测试
点击【测试】打开测试面板：
- 请求参数会按位置自动分到 Query、Body、Header 页签。
- 发送后展示响应体、HTTP 状态、耗时与结果大小。
- 脚本、单表、代理、编排四种模式均支持在线测试。
测试通过后，可以把请求保存为 测试用例，用于后续回归。开发阶段没有真实数据时，也可以配置 Mock 数据。
5. 保存并发布
- 新接口必须先 保存，否则【发布】按钮不可用。
- 点击 【发布】，选择目标环境（如
dev、生产环境）。 - 发布会在
base_api_release生成该环境的发布快照，接口进入已发布状态。 - 需要对外展示时，把权限级别设为 公开；只有「公开 + 生产环境 + 已上线」的接口会出现在 API Hub。
已上线接口不允许直接编辑，需要先下线，否则返回 43002。发布后再次修改内容，需要重新保存并发布才能上线。
6. 创建调用凭证
进入【个人中心 → 调用凭证】，点击新建：
| 字段 | 说明 |
|---|---|
| AppCode | 凭证编码，唯一；MCP 端点路径会使用它 |
| AppKey | 简单认证时通过 X-AppKey 传递 |
| AppSecret | 签名认证时作为 HMAC 密钥 |
| 作用域 | 项目级（本项目接口）或接口级（仅授权接口） |
| 访问 IP 控制 | 可限制凭证只能在白名单 IP 调用 |
| 启用 MCP | 开启后该凭证可作为 MCP Server 接入 |
创建后请 妥善保存 AppSecret。
7. 授权接口
进入【服务管理 → 接口列表】，找到目标接口，点击【授权】，在弹窗中勾选一个或多个调用凭证。
- 项目级凭证可访问项目内符合条件的接口。
- 接口级凭证只能访问被明确授权的接口。
- 取消勾选即可解除授权。
8. 调用接口
开放接口通过网关访问，本地网关地址为 http://localhost:9600，实际路径由「环境前缀 + 项目前缀 + 接口地址」组成。
简单认证
curl "http://localhost:9600/api/demo/orders/list?status=paid" \
-H "X-AppKey: ak_xxxxxxxxxxxxxxxx"
签名认证
签名认证需要 X-AppKey、X-Timestamp、X-Nonce、X-Sign，可选 X-Algorithm（签名算法默认 SM3，可切换 HmacSHA256）。当前版本的签名串还包含查询串与请求体的摘要，务必以 签名认证指南 为准，不要只按旧版三步拼接实现。
MCP 接入
凭证启用 MCP 后，可把 POST /mcp/{AppCode} 作为 MCP Server 地址，使用 X-AppKey 认证，支持 initialize、tools/list、tools/call。详见 MCP 服务接入。
常见失败点
| 现象 | 优先检查 |
|---|---|
40001 接口不存在或已下线 | 路径是否带全环境/项目前缀、接口是否已发布上线 |
40002 认证失败 | 凭证是否已授权该接口、作用域是否匹配 |
40008 缺少 AppKey | 请求头是否携带 X-AppKey |
40013 签名失败 | 签名串、请求体字节、query 原始串是否与发送内容完全一致 |
40021 订阅失效 | 是否已订阅、订阅是否过期或被冻结 |
40023 日配额超限 | 当日调用量是否达到订阅上限 |
41006 接口地址被占用 | 同环境、同请求方式下路径是否重复 |