接口设计约定

维护 Java 接口时先保持共享前端契约，再调整内部实现。开发环境访问 http://localhost:13001/swagger-ui.html 查看当前模型和路径；OpenAPI 是接口目录，调用仍需满足登录、权限及业务前置条件。

路径与版本

接口一般位于 /api/，但不是全部 /api/v1。例如当前用户为 /api/v1/user/info，菜单为 /api/v3/system/menus。以 Controller 和 art-design-pro-x-ui/src/api 的定义逐项核对，不批量替换版本号。

普通 JSON 响应

Controller 使用 com.artd.common.core.domain.R<T>：

json

{
  "code": 200,
  "msg": "操作成功",
  "data": { "id": 1 }
}

成功业务码为 200，消息字段是 msg。Service 返回业务值，Controller 再包装 R.ok(...)。文件、SSE、支付回调按各自协议返回，不能套用普通 JSON 包装。

分页

请求常用 current、size，具体默认值和上限由资源 DTO 决定。分页数据对象为：

json

{
  "total": 1,
  "records": [{ "id": 1 }],
  "current": 1,
  "size": 10,
  "pages": 1
}

事实源是 art-common-core 的 page/PageResult.java，MyBatis 分页转换位于 art-common-mybatis 的 page/MybatisPageResults.java。不要对已适配的接口改成另一套 rows/pageNum；特殊响应在单个页面适配。

例：查询系统参数

在开发环境登录后，用已有接口调试工具发送以下请求，Bearer 后替换为当前会话的 Access Token：

http

GET /api/v1/system-params?current=1&size=10&enabled=true
Authorization: Bearer <当前会话的 Access Token>

此接口要求 system:param:list 权限。current 从 1 开始，size 默认 10、最大 500；还支持 keyword、groupCode、valueType、builtIn 筛选。分页结果在普通响应的 data 内，另有分组和统计字段，因此不要丢弃分页基本字段之外的业务数据。

对应源码是 settings/controller/SystemParamController.java、settings/dto/SystemParamQuery.java 和 settings/vo/SystemParamListVO.java。这些默认值属于本接口，其他列表请查看各自 DTO。

请求与模型

DTO 使用 Jakarta Validation 校验格式、长度与必填字段。
依赖身份、数据库状态或业务关系的判断放在 Service。
Entity 负责表映射，VO 负责响应；Mapper 接收域内查询模型或写入命令。
动态表单可使用 JSON 树，但稳定外围字段仍应类型化，不将整个业务建成裸 Map。
SQL 值参数绑定，动态排序与列名走白名单。

PATCH 必须区分三种状态

输入	需要保留的语义
字段未提交	通常保持旧值，但以对应 DTO/Service 为准
显式 `null`	可能清空，也可能因必填被拒绝
实际值，包括空字符串或空数组	按该字段业务规则更新或清空

不能将所有 DTO 的 null 判断统一改写成同一种行为。例如商城支付凭据中缺省或空字符串保留旧值，null 尝试清空；售后须知正文则有不同清空规则。修改前同时读取请求类型、Service 和测试。

日期、金额与错误

基础 JSON 配置使用 GMT+8，但不是所有业务都使用相同格式。部分响应通过 JsonLocalDateTime 保留具体格式，商城时间采用 UTC ISO，商品与订单金额使用整数分。不要通过全局序列化修改修复单个页面。

业务码不总等于 HTTP 状态。商城 MallResponseStatusAdvice 在商城路径内映射错误 HTTP 状态，AI 建流前错误也遵循其单独处理。前端应检查所属接口的 HTTP 与业务响应，不能把所有 HTTP 200 当业务成功。

变更接口前

确认调用方、DTO/VO、默认值、错误顺序、权限码和测试。兼容变更同时考虑前端封装与已有客户数据；不要为方便生成文档修改生产协议。

商城精确端点目录位于 art-system/src/test/resources/mall/endpoints.json，权限目录快照位于 art-admin/src/test/resources/contracts/。快照用于测试，不是运行时配置；新增接口需同时更新真实实现和对应验证。

接口设计约定 ​

路径与版本 ​

普通 JSON 响应 ​

分页 ​

例：查询系统参数 ​

请求与模型 ​

PATCH 必须区分三种状态 ​

日期、金额与错误 ​

变更接口前 ​