快速接入¶
接入步骤¶
- 从 App 或管理后台目录选择已实现的接口,核对环境、方法、路径和权限。
- 配置接口服务地址与公共请求头,按发行渠道选择统一渠道代码,发送版本、构建号、设备 ID 及每次请求的 ID/时间戳;有 JSON 正文时设置
Content-Type。 - 统一处理 HTTP 状态、业务
code和字段errors,成功时把data交给业务页面。 - App认证按登录注册接入处理Bearer凭证、刷新和注册进度;当前dev手机号和邮箱固定验证码均为123456,仍须先向服务器申请challengeId,不发送短信邮件。
正式部署地址(上线前阶段)¶
以下地址属于唯一一套正式部署环境,没有独立测试服;当前仍在上线前开发和验收,运行配置与正式开放准备见接入入口。
- 接口服务地址:
https://api.budyoo.cn。 - App 文档:App 接口目录。
- 管理后台文档:管理后台接口目录。
- API、文档和管理后台域名均已完成公网HTTPS可达性检查;API当前运行配置保留
dev,协作者使用这些正式域名按现有认证契约联调。官网https://budyoo.cn/已完成公网静态页面验收。
基础连通性与语言请求示例:
curl --fail-with-body \
-H 'Accept: application/json' \
-H 'Accept-Language: zh-CN' \
'https://api.budyoo.cn/api/v1/system/info'
需要测试完整 POST、元数据及参数错误时,使用标准请求测试,其中列有完整请求头和真实用例结果。
JavaScript 请求封装¶
可直接下载 budyoo-client.mjs 放进网页工程,使用原生 fetch,无需第三方包,也可由支持 fetch 的 Node.js 导入。支持查询参数、JSON 正文、动态语言、超时、取消、HTTP/业务错误及非 JSON 响应;默认只允许 HTTPS,不自动重试或向其他地址重定向。
import { createBudyooClient, BudyooApiError, getOrCreateDeviceId } from './budyoo-client.mjs';
// 示例使用浏览器本域存储;每次请求不重新生成设备 ID。
const deviceId = getOrCreateDeviceId(localStorage);
const api = createBudyooClient({
baseUrl: 'https://api.budyoo.cn',
getLanguage: () => 'zh-CN',
getClientMetadata: () => ({
clientType: 'admin', platform: 'web',
appVersion: '1.0.0', appBuild: '1', channel: 'admin_web', deviceId,
}),
timeoutMs: 15000,
});
try {
const result = await api.request({
path: '/api/v1/system/request-test', method: 'POST',
body: {message: 'Budyoo 接口测试', number: 7},
});
console.log(result.passed, result.language);
} catch (error) {
if (error instanceof BudyooApiError) {
// 根据 kind、httpStatus、code、errors 更新页面,不把 message 当业务码。
console.error(error.kind, error.httpStatus, error.code);
}
}
此封装只用于统一业务响应。Actuator 健康检查采用独立结构,应直接发送 HTTP 请求。管理后台真实业务尚未实现,当前可用公共系统信息接口验证网络封装。
getClientMetadata 从发布配置和本地存储读取版本等稳定信息;封装自动为每次请求生成 X-Request-Id、X-Request-Timestamp。版本、渠道和设备字段本身不具备认证作用,不等同于风控通过或签名验证。
Node.js 调用时,将本域存储替换为调用方持久保存的安装 UUID;自动验证脚本内的设备 ID 为临时合成测试数据。未知系统版本或设备型号可以不传。
当前 baseUrl 使用已验证的 HTTPS 地址,无需开启 allowInsecureDevelopment。页面在请求前设置加载状态,在 finally 中恢复;cancelled 通常无需提示,timeout/network 提供重试入口,401/403 分别处理身份与权限,VALIDATION_FAILED 对应字段展示 errors。
浏览器跨域需要服务端明确允许对应后台网页来源;当前优先同源调用,未设置任意来源 CORS。HTTP 页面/不同域名/不同端口不会自动获得跨域权限。
Flutter 请求封装¶
现有 Flutter 工程已具备 DioManager、AppHttpRequest 与 BaseModel.sendApi。业务模块通过 BaseModel.sendApi 发起请求,路径统一登记在 ApiServe;统一层注入 Accept-Language、解析 code/message/data/errors、处理超时取消与错误提示。
系统信息路径为 ApiServe.systemInfo,方法为 GET,无请求体。现有独立真实接口测试可验证健康、语言及 401;页面业务仍需按实际流程接入。
当前Flutter统一网络层已具备版本/渠道/设备元数据和每请求ID/时间戳注入。登录注册页面接入时继续复用该能力,将新路径登记到ApiServe,并在认证扩展点注入Bearer凭证。本批后端验证不代表Flutter登录页面或三方SDK已经完成真实认证联调。
不要在页面中重复封装一套HTTP或加密算法。现有认证扩展点接入本次Bearer协议;刷新需在统一网络层串行处理,客户端不保存服务端私钥或共用的硬编码秘密。
长连接接入¶
建立长连接说明 WebSocket 票据、认证与心跳;提供独立的 JS 连接封装,处理退避重连和释放资源。HTTP 请求封装与连接管理分别复用,WebSocket 事件不套 HTTP 状态码。当前未实现 Flutter 长连接管理器或聊天业务。
AES 报文加密¶
JSON 接口可在 createBudyooClient 中注入 encryption: createJweEncryption(...),调用方仍传原 JSON 字段;密钥交换、AES-GCM、响应验证由统一适配器处理。详见AES 请求与响应加密和获取接口公钥。
加密响应读取期间发生超时或主动取消时,kind 仍分别为 timeout/cancelled;真正的密文认证失败为 encryption,不能展示为可信业务返回。封装不会自动重试写操作。
当前dev运行配置保留既有App明文JSON兼容,启用加密模块的prod配置强制约定范围内JSON接口使用密文;后台JSON业务始终要求JWE。客户端接入仍须按契约验收,不能直接设置加密请求头而不做真实加解密。AES 不取消 HTTPS/WSS 与业务认证要求。