{ "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": "接口错误: " } ], "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" ] } ] }