161 lines
7.0 KiB
JSON
161 lines
7.0 KiB
JSON
{
|
||
"module": "openapi",
|
||
"description": "开放 API 统一入口,独立链路,HTTP POST /openapi,记录入口校验/鉴权规则与返回格式。",
|
||
"version": "2026.04.26-openapi-04",
|
||
"updatedAt": "2026-04-26",
|
||
"http": {
|
||
"path": "/openapi",
|
||
"method": "POST"
|
||
},
|
||
"headers": [],
|
||
"endpoints": [
|
||
{
|
||
"method": "openapi.index",
|
||
"description": "开放 API 统一入口,接收 POST /openapi;完成 JSON body 解析、app_key 校验与签名校验,返回统一响应(与系统 style 的 code/message/data 保持一致)。",
|
||
"isNeedAuth": false,
|
||
"isNeedLogin": false,
|
||
"headers": [],
|
||
"params": [
|
||
{
|
||
"name": "method",
|
||
"type": "string",
|
||
"required": true,
|
||
"source": "query",
|
||
"description": "目标系统方法名,必填(例如 order.list)"
|
||
},
|
||
{
|
||
"name": "v",
|
||
"type": "string",
|
||
"required": true,
|
||
"source": "query",
|
||
"description": "API 版本号"
|
||
},
|
||
{
|
||
"name": "timestamp",
|
||
"type": "number",
|
||
"required": true,
|
||
"source": "query",
|
||
"description": "时间戳(数字)"
|
||
},
|
||
{
|
||
"name": "app_key",
|
||
"type": "string",
|
||
"required": true,
|
||
"source": "query",
|
||
"description": "开放平台分配的 app_key;兼容别名 appkey 与 self_app_key(任一存在即可)"
|
||
},
|
||
{
|
||
"name": "sign",
|
||
"type": "string",
|
||
"required": true,
|
||
"source": "query",
|
||
"description": "签名字段,兼容别名 signature(MD5 小写 hex)"
|
||
}
|
||
],
|
||
"requestBody": [
|
||
{
|
||
"name": "body",
|
||
"type": "object",
|
||
"required": true,
|
||
"source": "body",
|
||
"description": "请求体必须为 JSON;入口优先读取 rawBody,空体或非 JSON 返回 400,错误文案为 'json数据为空' 或 'json数据解析错误'。"
|
||
}
|
||
],
|
||
"response": [
|
||
{
|
||
"name": "code",
|
||
"type": "number",
|
||
"required": true,
|
||
"description": "业务码:成功通常为 1"
|
||
},
|
||
{
|
||
"name": "message",
|
||
"type": "string",
|
||
"required": true,
|
||
"description": "提示消息"
|
||
},
|
||
{
|
||
"name": "data",
|
||
"type": "object",
|
||
"required": false,
|
||
"description": "接口返回数据"
|
||
},
|
||
{
|
||
"name": "timestamp",
|
||
"type": "number",
|
||
"required": true,
|
||
"description": "响应时间戳"
|
||
}
|
||
],
|
||
"errors": [
|
||
{
|
||
"code": 400,
|
||
"message": "参数缺失或错误: method/v/timestamp 或 app_key"
|
||
},
|
||
{
|
||
"code": 400,
|
||
"message": "json数据为空"
|
||
},
|
||
{
|
||
"code": 400,
|
||
"message": "json数据解析错误"
|
||
},
|
||
{
|
||
"code": 401,
|
||
"message": "app_key 无效或不可用"
|
||
},
|
||
{
|
||
"code": 401,
|
||
"message": "签名校验失败"
|
||
},
|
||
{
|
||
"code": 500,
|
||
"message": "接口错误: <message>"
|
||
}
|
||
],
|
||
"notes": [
|
||
"独立链路:/openapi 为独立入口,不依附于 system/qimen,不复用系统的请求头强校验或鉴权链。",
|
||
"不校验 platform/project 等请求头:openapi 不对 platform/project 请求头做强制校验或拒绝,headers 字段为空。",
|
||
"body 使用 JSON 解析:content-type 应包含 application/json;优先读取 ctx.request.rawBody,若未提供则回退到 ctx.request.body 或原始请求流;空体或解析失败返回 400(错误消息为 'json数据为空' 或 'json数据解析错误')。",
|
||
"app_key 校验:通过数据库表 wms_api_app(或对应模型)按 self_app_key/app_key 查询,要求 is_enabled=1 且 interface_type_id=2(OPEN_API 类型)才视为有效,否则返回 401(消息 'app_key 无效或不可用')。",
|
||
"签名规则:构建 canonicalQuery(取 query 参数,支持别名 app_key/appkey/self_app_key,签名字段支持 sign/signature;排除签名字段本身),按 key 的字母序排序并用 & 连接 key=value;计算 bodySign 为 md5(稳定序列化(body));将 canonicalQuery + self_app_secret + bodySign 连接成字符串并对该字符串计算 md5(小写 hex),结果与请求中 sign/signature 比对,匹配即通过。",
|
||
"method 分发:openapi 的 method 分发走 openapiMethods 专用目录(代码内实现独立路由/分发);已存在方法示例:index.ping(模块=基础模块)。",
|
||
"返回风格:成功与失败返回使用与系统一致的 code/message/data 格式(无需额外 flag 字段),以保证与系统端点兼容。"
|
||
]
|
||
},
|
||
{
|
||
"method": "index.ping",
|
||
"description": "基础模块 心跳接口,返回服务可用性(部署在 openapiMethods 中)",
|
||
"isNeedAuth": false,
|
||
"isNeedLogin": false,
|
||
"headers": [],
|
||
"params": [],
|
||
"response": [
|
||
{
|
||
"name": "code",
|
||
"type": "number",
|
||
"required": true,
|
||
"description": "业务状态码,成功通常为 200 或 1"
|
||
},
|
||
{
|
||
"name": "message",
|
||
"type": "string",
|
||
"required": true,
|
||
"description": "提示信息"
|
||
},
|
||
{
|
||
"name": "data",
|
||
"type": "object",
|
||
"required": false,
|
||
"description": "返回数据,ping 一般为空或包含版本/uptime 等信息"
|
||
}
|
||
],
|
||
"errors": [],
|
||
"notes": [
|
||
"模块:基础模块",
|
||
"方法部署位置:openapiMethods/index.ping"
|
||
]
|
||
}
|
||
]
|
||
}
|