业务 API 与 H5 / 小程序联调

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

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

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

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

配置或请求	示例
后端配置	server.port=8100、server.context-path=/admin
Java 内部注册路径	/api/app/resources
客户端完整地址	http://127.0.0.1:8100/admin/api/app/resources
后台登录完整地址	http://127.0.0.1:8100/admin/api/login/account

内部路径不重复添加上下文前缀。接口文档可以用 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：

import com.jfinal.kit.Kv;
import nexus.io.model.body.RespBodyVo;
import nexus.io.tio.boot.http.TioRequestContext;
import nexus.io.tio.utils.validator.ParameterValidator;

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。动态表单与可选更新可以使用 Kv 参数集合；确定的字段使用请求实体。Service 保留分类表单、数据库状态、对象归属与事务校验。不要将任意参数集合直接作为数据库更新列。

HttpRequest.getRequestMap() 只返回查询和已解析表单参数，不解析 JSON，不改变原有 getParam/getLong 的取值规则。JSON 正文使用 getBodyObject() 绑定请求实体；动态字段可绑定为 Kv。支付验签直接使用 getBodyString() 保留原始正文。业务层不写死请求大小限制，请求大小由 HttpConfig 和框架 HTTP 解码器统一处理。http.max-request-body-size 可单独限制非 multipart 请求的正文大小，单位为字节。完整语义见 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 支持该设置，需要仅对部分业务响应做转换时，也可显式调用 ResponseValueNormalizer.normalize(data)，统一处理嵌套 Long、Timestamp、JSON/JSONB 和 record，见 请求校验与响应转换。切换其他 JSON provider 时，应验证所选实现的整数序列化行为。

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

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

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

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

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

类型	业务入口必须检查
公开接口	仅返回允许公开的字段，例如分类、已审核资源
登录用户接口	用户 Token、有效期、会话状态以及用户是否禁用
管理员业务操作	管理员身份、账号状态和操作权限，例如审核、退款

若管理员操作也位于被放行的前缀内，必须在业务入口重新检查管理员权限。不要将整个前缀都当作公开接口，也不要放行 /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. 测试与启动排查

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

层次	应验证的内容
单元测试	参数和动态字段校验、BIGINT 转换、错误响应、加解密边界
PG 集成测试	权限与租户隔离、事务回滚、并发扣减、请求幂等、原图保留
真实 HTTP 测试	上下文前缀、方法限制、匿名拒绝、两类 Token 互相拒绝、错误 JSON
前端构建与浏览器	H5 / 小程序构建、页面路由、响应式布局、空状态及失败交互
第三方与真机	实际登录、上传、支付；未接入时明确记录未验证

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 分支和循环体使用大括号。

import com.jfinal.kit.Kv;
import nexus.io.model.body.RespBodyVo;
import nexus.io.tio.boot.http.TioRequestContext;
import nexus.io.tio.utils.validator.ParameterValidator;

Kv parameters = request.getBodyObject(Kv.class);
String phone = ParameterValidator.text(parameters.get("phone"), "phone", 11);
ParameterValidator.require(phone.matches("1[3-9][0-9]{9}"), "请输入大陆手机号");
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.model.exception.BusinessException，不必在每个应用重复声明。构造参数为 HTTP 错误状态和可向客户端展示的消息，可选第三个参数保留原始异常。状态范围为 400～599，通过 getStatus() 读取。该异常由 java-model 提供；需要稳定业务错误码时，使用 new BusinessException(status, code, message)，通过 getCode() 读取，应用无需再声明同名异常。

import nexus.io.model.exception.BusinessException;

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)。