业务 API 与 H5 / 小程序联调

本章补充使用 tio-boot-admin（nexus.io 包名）开发 PostgreSQL 业务项目时的接口约定和验证方法。响应格式、用户会话、业务表和第三方占位是业务工程的实现选择，不是框架自动提供的能力。

1. 保留后台配置，增加业务入口

继续使用 01.md 的六个内置配置调用。后台登录与 ApiTable 保留原有注册，只新增项目业务路由。不要为了开发移动端而重写连接池、重复安装后台拦截器或默认加入 Sa-Token。

例如给普通用户 API 约定 /api/app 前缀：

内部路径不重复添加上下文前缀。接口文档可以用 servers 描述 /admin/api/app，再以 /resources 描述业务路径；客户端按同一个约定拼接。

推荐使用 router.get/post 或 router.add(HttpMethod.POST, path, handler, metadata) 显式声明方法，并在 doBeforeRoute 拦截器中认证用户。框架生成 405 与 Allow，业务 Handler 不再重复检查方法。旧 add(path, handler) 仍是 ANY。完整迁移见 方法路由与业务鉴权。

路由、拦截器、Handler 与 Service 分层

建议独立维护路由配置与拦截器配置，运行时按以下职责处理：

拦截器 → Handler → Service → Db
           │          │
       解析 HTTP 参数  返回 Kv / RespBodyVo
           │
       response.setJson(...)

• 路由配置只登记 HTTP 方法、路径、Handler 方法引用和权限 metadata。框架路由器已经保存这些信息，无实际消费方时不再维护第二份路由 List。
• 拦截器读取匹配路由的权限声明，验证身份并写入请求上下文；业务对象归属、状态变更与事务仍在 Service 中校验。
• Handler 按业务模块拆分，解析查询参数、JSON、请求头或上传文件，将 ID、分页、业务参数对象交给 Service。支付回调应传递原始正文和验签请求头，不先重新序列化正文。
• Service 不依赖 HttpRequest、HttpResponse，负责业务与数据库操作。返回 Kv 或 RespBodyVo，推荐业务接口使用 RespBodyVo；已返回响应对象时，Handler 不再套一层 RespBodyVo.ok(result)。
• Handler 使用 TioRequestContext.getResponse().setJson(result) 输出，也可使用 Resps.json；不需要再包装一套业务 JSON 响应类。统一异常转换通过 TioBootExceptionHandler 实现，并使用 TioBootServer.me().setExceptionHandler(...) 注册。

例如 Handler 中完成参数提取后调用 Service：

Kv parameters = Kv.create().set(request.getRequestMap());
long resourceId = ParameterValidator.id(parameters.get("id"), "id");
RespBodyVo result = resourceService.detail(resourceId);
return TioRequestContext.getResponse().setJson(result);

RespBodyVo 的导入路径为 nexus.io.model.body.RespBodyVo，ParameterValidator 位于 nexus.io.tio.utils.validator。Handler 使用它检查参数格式、长度、枚举和范围，失败时将 ParameterValidationException 转换为 400。动态表单与可选更新可以使用规范化的 Map 参数集合；Service 保留分类表单、数据库状态、对象归属与事务校验。不要将任意参数集合直接作为数据库更新列。

HttpRequest.getRequestMap() 合并查询/已解析表单参数与 JSON 对象，JSON 同名字段优先，不改变原有 getParam/getLong 的取值规则。支付验签直接使用 getBodyString() 保留原始正文。业务层不写死请求大小限制，请求大小由 HttpConfig 和框架 HTTP 解码器统一处理。完整语义见 HttpRequest。

Service、DAO 等需要复用的对象通过 nexus.io.jfinal.aop.Aop.get(...) 获取。通常只执行一次的配置类直接 new 并调用 config()；Handler 在路由配置中直接 new，由注册的方法引用保存在 HttpRequestRouter 中，无需再放入 Aop。拦截器和异常处理器也可直接创建，由其注册位置持有。Handler 内部依赖的 Service 仍通过 Aop 获取，以共享登录会话等服务状态。依赖环境选择的适配器、加密密钥等对象，在首次获取依赖它们的服务之前用 Aop.put(Type.class, instance) 注册。依赖直接在字段中初始化，例如 private final CommerceService commerce = Aop.get(CommerceService.class);，无需额外编写依赖构造器。隔离测试先用 Aop.put 注册依赖，再获取被测对象；需要独立实例时使用 Aop.getPrototype。不要创建业务服务后再替换容器中的依赖，已持有的引用不会自动更新。

当前 Aop 创建对象时会生成子类代理，因此交给 Aop.get 创建的 Service、DAO 等类不要声明为 final，并提供可用的无参构造器。已经通过 Aop.put 注册的实例可以由应用使用必要的构造参数创建。

BIGINT 的序列化使用框架 JSON 能力，例如启动时 Json.setLongToString(true)；默认 Mixed/TioJson 及 FastJson2 支持该设置，无需在业务层递归转换 Map/List。切换其他 JSON provider 时，应验证所选实现的整数序列化行为。

2. 后台与普通用户分别鉴权

后台管理员 Token 与普通用户 Token 应有明确边界。业务用户身份不能直接作为 ApiTable 的后台权限。

可以在已经实现独立鉴权的业务入口前提下，将原来的一次后台拦截器配置替换为：

new TioAdminInterceptorConfiguration(new String[] {"/api/app/**"}).config();

该调用仅让后台拦截器跳过此路径，不会安装业务鉴权。业务路由应集中登记以下访问类型，默认拒绝未声明权限的接口：

若管理员操作也位于被放行的前缀内，必须在业务入口重新检查管理员权限。不要将整个前缀都当作公开接口，也不要放行 /api/table/**。

独立签发用户 JWT 时使用独立签名密钥，并校验项目约定的受众等声明。仅仅换请求头名称不能隔离两种身份。框架默认 Token 验证与退出行为见 03.md，不要承诺默认 JWT 具有持久化撤销能力。

会话可按项目规模选择进程内存或 PostgreSQL。内存会话在进程重启后失效，也不能自然支持多实例；需要共享会话时可以使用 PG，并由用户手动执行新增表的 SQL，不必直接引入 Redis。

每个查询与写入还需检查资源归属、租户和逻辑删除状态。登录成功不等于可以读取其他用户的草稿、订单或私聊。

3. 先确定客户端数据契约

BIGINT 与金额

PostgreSQL BIGINT、Java Long 可以超出 JavaScript Number 的安全整数范围。ID、消息序号等字段建议始终作为十进制字符串传输：

{
  "code": 1,
  "msg": "ok",
  "data": {
    "id": "9223372036854775807",
    "amount_cent": "1990"
  }
}

在后端 DTO 或业务响应转换层完成转换，覆盖嵌套对象和列表。不要等前端 JSON 解析完成后再 String(id)，此时精度可能已经丢失。也不要为业务接口未经验证就全局改变后台 ApiTable 的序列化行为。

金额可使用最小货币单位的整数；展示时按字符串处理小数位置。下单金额、权益和余额始终由后端计算。序号排序不能使用 Number(a) - Number(b)；对非负十进制整数字符串，可去除前导零后先比较长度，再比较字典序。

成功、错误与分页

上面的 code/msg/data 是本章业务约定。项目可以选其他格式，但应明确成功码、分页参数和错误码，不能推断所有框架接口都采用相同封装。

客户端同时检查 HTTP 状态和业务码。uni.request 收到 HTTP 错误响应时也可能进入响应回调，不能把回调执行当作业务成功。建议区分 401（登录失效）、403（无权操作）、405（方法错误）和第三方未接入状态。

ApiTable 示例使用 current/pageSize，业务 API 可以使用 page/pageSize，但前后端和 OpenAPI 必须保持一致。服务端限制最大页大小、限定排序字段，并为列表定义稳定的第二排序键，避免翻页时遗漏或重复。

4. PG 表与业务事务

业务表可沿用 id、creator、create_time、updater、update_time、deleted、tenant_id 等管理字段，表名前缀由项目统一约定。字段存在不会自动完成租户隔离、权限判断或更新时间维护，业务 SQL 仍须落实这些条件。

外键是否使用应在建表文档中明确。选择逻辑关联时，数据库不会自动阻止孤儿记录，需由事务、写入校验和删除策略保证一致性；选择外键时，也要说明删除规则。不要把任一种选择写成框架强制要求。

以下操作应放在同一个数据库事务中：

• 解锁联系方式：检查可用额度、扣减、保存解锁记录及流水。
• 支付履约：确认有效支付通知、更新订单、发放权益。
• 聊天发送：分配会话内序号、保存消息、更新会话状态。

需要重试的写入定义请求号，服务端以唯一约束和事务保证同一次操作只生效一次。请求号必须绑定用户与业务参数；客户端重试复用同一请求号，不能每次重试重新生成。

普通搜索和消息轮询可先由 PG 实现，根据实际查询计划、数据量与并发再评估额外中间件。保留标准 Redis / MongoDB 配置调用而不提供 host 的行为见 03.md。

所有业务建表与升级 SQL 仍由用户手动执行，应用启动不自动初始化生产数据库。

5. 公开详情与编辑详情分开

公开列表和详情应显式选择可见字段，不直接序列化整行记录。联系方式、内部审核信息、支付参数等按业务权限提供。

编辑已有图片时，前端可能需要保存原图片的对象键。可在验证资源所有者后由编辑详情返回对象键；公开详情仅返回展示所需的 URL 等字段。再次保存时还要验证对象键属于当前用户或允许复用的原资源，不能因为客户端传入对象键就认可归属。

动态表单应在后端再次检查字段白名单、类型、必填项、长度和枚举。前端清空可选数字或枚举字段时，应按约定省略字段或传 null，不要把空字符串强转成数字 0。草稿和提交审核可采用不同必填规则，但类型检查不能完全跳过。

6. 未接入第三方时明确返回状态

短信、微信身份交换、文件存储、认证、支付和 AI 可通过业务 adapter 隔离。尚未实现的能力可以统一返回 HTTP 501 和明确业务提示；若只是临时不可用，则应使用项目约定的服务不可用状态。该行为需要业务工程显式实现，不是框架默认行为。

发送短信：校验请求 → 调用短信 adapter → 供应商确认后返回已发送
微信登录：取得临时 code → 服务端换取身份 → 验证并签发用户会话
支付通知：验证签名与订单信息 → 事务内幂等履约 → 返回供应商约定结果

未接入时在 adapter 边界返回，不生成万能验证码、伪造用户身份或将订单直接标记已支付。前端也不能用定时器、固定 Token 或本地存储模拟成功。保留伪代码时注明输入、成功条件及需要接入的客户端步骤，例如真实文件流上传和支付 SDK 调用。

7. H5 与小程序地址分别配置

H5 开发时可由 Vite 将 /admin 代理到后端 http://127.0.0.1:8100，保留该路径前缀；客户端请求 /admin/api/app。生产环境配置同等的反向代理，或设置完整 API 地址并配置对应跨域规则。

小程序请求不经过 H5 的 Vite 代理，需要单独配置可访问的后端地址。真机中的 127.0.0.1 指手机自身。小程序 AppID、HTTPS 服务地址与平台域名配置需在实际环境补齐，不能用“小程序编译成功”代替真机验收。

客户端环境变量只能包含公开配置，例如 API 地址和公开 AppID。数据库密码、JWT 签名密钥和微信 AppSecret 必须留在服务端。

使用 pnpm 的 uni-app 工程应提交 pnpm-lock.yaml，保留官方模板兼容的 DCloud 依赖组合。H5 和小程序分别构建，避免只验证浏览器编译；共享模板表达式尽量使用命名方法，遇到小程序模板编译错误时检查生成端限制。

8. 测试与启动排查

建议按以下层次记录验证结果：

PG 集成测试使用专用测试库，或每次创建独立随机 schema 并将所有测试连接的 search_path 限定于该 schema。只有测试夹具执行测试 SQL；测试结束只清理本次创建的 schema，不在用户业务 schema 中初始化或清空数据。

HTTP 客户端测试应检查 Content-Encoding，收到 gzip 时先解压再解析 JSON，避免把传输压缩错误判断为业务响应错误。具体是否压缩取决于实际响应。

Windows 上正在运行的可执行 JAR 可能导致 Maven 重打包时出现文件占用。先核对并停止当前项目自己的 Java 进程，再打包、启动；不要停止电脑上的全部 Java 进程。启动后读取健康接口或公开查询确认服务可用，不只检查进程是否存在。

最终报告分别列明单元测试、数据库测试、HTTP 验证、前端构建及第三方验收结果。没有真实登录凭据时，匿名页面测试不能证明全部登录后流程已经端到端通过。

源码核对位置

• tio-boot-admin-web：TioAdminInterceptorConfiguration、TioAdminHandlerConfiguration、TioAdminControllerConfiguration。
• tio-boot-admin-base：TioAdminDbConfiguration、TioAdminRedisDbConfiguration、TioAdminMongoDbConfiguration。
• tio-boot：TioApplicationContext 中上下文路径读取和 HTTP 配置。

升级版本后先核对上述实现，再更新文档中的框架行为；不要把本章业务工程的设计约定误当作新增的框架配置项。

直接输出服务结果与异常处理

服务返回 RespBodyVo 时，Handler 可以直接输出：

RespBodyVo serviceResult = commerce.products();
return TioRequestContext.getResponse().respond(serviceResult);

HttpResponse.respond(RespBodyVo) 使用 setJson 序列化结果，不修改消息，也不覆盖已设置的 HTTP 状态。业务没有设置 msg 时，不补充 "ok"。

Java 会先调用服务，再将结果传入 respond；因此服务执行期间的异常由框架请求调度器捕获，交给应用注册的 TioBootExceptionHandler。异常处理器设置响应状态并返回错误结果，例如将参数异常转换为 400、业务异常转换为对应状态、未知异常转换为 500；未知异常响应不暴露内部错误详情。respond 本身不承担服务异常捕获职责。

Handler 与 Service 的可读性约定

Handler 先解析并校验参数，使用明确类型的局部变量，再调用 Service，最后输出响应。不要将参数校验和分页转换嵌在 Service 方法的实参中。应用代码不使用 var，所有 if/else 分支和循环体使用大括号。

Kv parameters = Kv.create().set(request.getRequestMap());
String phone = MiValidators.validatePhone(parameters.get("phone"));
String code = ParameterValidator.text(parameters.get("code"), "code", 12);
Long inviterUserId = parameters.containsKey("inviterUserId")
    ? ParameterValidator.id(parameters.get("inviterUserId"), "inviterUserId")
    : null;

RespBodyVo serviceResult = auth.smsLogin(phone, code, inviterUserId);
return TioRequestContext.getResponse().respond(serviceResult);

Service 先执行事务、获取结果，再构造响应；事务内失败时抛异常，避免把事务调用嵌进响应工厂方法。

Kv result = Db.txResult(() -> {
  // 执行业务 SQL，返回业务结果；需要回滚时抛异常。
  Kv data = Kv.create();
  data.put("id", orderId);
  return data;
});
return RespBodyVo.ok(result);

复用框架 BusinessException

业务异常统一使用 nexus.io.tio.boot.exception.BusinessException，不必在每个应用重复声明。构造参数为 HTTP 错误状态和可向客户端展示的消息，可选第三个参数保留原始异常。状态范围为 400～599，通过 getStatus() 读取。

BusinessException.require(allowed, 403, "Permission denied");
BusinessException.require(valid, "Invalid operation"); // 默认 400
throw new BusinessException(409, "Conflicting record", cause);

当应用没有通过自定义异常处理、ThrowableHandler 或错误页面完成响应时，tio-boot 的默认异常处理会将直接抛出的 BusinessException 转为对应 HTTP 状态和 RespBodyVo.fail(message)。已配置的自定义异常处理器仍优先；如果它返回了响应结果，框架不会再覆盖该结果。

米旺的 MiExceptionHandler 使用同一个框架异常类，并继续处理参数校验异常和未知异常。java-db 不依赖 HTTP 业务异常，数据库 SQLState 到业务状态的转换仍由应用完成。

业务 Handler、Service 和 Store 的业务参数与记录使用 com.jfinal.kit.Kv，列表使用 List<Kv>。先在 Handler 校验输入，Service 再通过 getLong、getInt、getStr 等方法读取，减少重复的强制转换；需要返回业务响应时继续使用 RespBodyVo.ok(result)。