标准 CRUD 接口规范¶

📄 创建: ZCode AI 2026-08-14 · 修改: JimWb 2026-08-14

https://doc.xpku.com/raw/tech/backend/api-standards/crud-spec.md

BAMS 体系所有继承 EnergyBaseController 的 Controller 都自动提供同一套标准 REST 接口（21 个）。前端只需掌握这一套规范，即可调用系统中任何标准业务模块的增删改查。 本文档给前端开发和前端 AI 快速调用使用。

一、全局约定¶

1.1 基础信息¶

1.2 登录鉴权（sessionid Header）¶

登录成功后拿到 sessionId，后续所有请求放在 HTTP Header 里传递：

sessionid: 550e8400-e29b-41d4-a716-446655440000

• Header 名固定小写 sessionid
• 会话有效期 1 天（Redis）
• 标了 @IgnoreSession 的接口免登录

1.3 统一响应格式（JsonResult）¶

所有接口（除文件下载类）统一返回：

{
  "code": "200",           // 响应码，"200"=成功
  "msg": "操作成功",        // 提示消息
  "result_explain": null,   // 结果说明
  "fail_args": null,        // 失败参数
  "data": { ... },          // 业务数据（泛型 T）
  "error_msg": null         // 错误详情（失败时有异常栈）
}

常见响应码：

1.4 分页响应格式（MyBatis-Plus Page）¶

分页接口的 data 是 Page 结构：

{
  "code": "200",
  "data": {
    "records": [ ... ],     // 当前页数据数组
    "total": 128,           // 总条数
    "size": 10,             // 每页条数
    "current": 1,           // 当前页码
    "pages": 13             // 总页数
  }
}

二、查询参数格式（BasicParamWrapper）—— 核心¶

/list、/listCommon、/dict、/tree、/first、/last、/listMap、/deleteByParams 都接收同一个查询参数结构。掌握这一个 JSON 格式 = 掌握所有标准模块的条件查询。

2.1 完整参数结构¶

{
  "searchVal": "关键词",
  "current": 1,
  "size": 10,
  "andMap":     { "status": 1, "corp_code": "C001" },
  "likeMap":    { "name": "张" },
  "andLikeMap": { "code": "BM-" },
  "rightLikeMap": { "name": "三" },
  "geMap":      { "created_time": "2026-01-01 00:00:00" },
  "leMap":      { "created_time": "2026-12-31 23:59:59" },
  "inMap":      { "type": ["A", "B"] },
  "notInMap":   { "status": [0, 9] },
  "orMap":      { "name": "李,王" },
  "orderBy":    { "created_time": "desc" },
  "columns":    ["id", "name", "status"]
}

2.2 字段说明¶

2.3 典型查询示例¶

分页 + 条件 + 排序：

POST /apex-api/bd/person/list
{
  "current": 1,
  "size": 20,
  "andMap": { "corp_code": "C001", "status": 1 },
  "likeMap": { "person_name": "张" },
  "geMap": { "created_time": "2026-08-01 00:00:00" },
  "orderBy": { "created_time": "desc" }
}

不带分页查全部（current/size 不传即查全部）：

POST /apex-api/bd/unit/list
{ "andMap": { "enable_state": 1 } }

区间查询：

{
  "geMap": { "amount": 100 },
  "leMap": { "amount": 5000 }
}

⚠️ 注意：条件 Map 的 key 用数据库列名（snake_case），不是实体属性名（camelCase）。如 corp_code 而非 corpCode。

三、21 个标准接口清单¶

以下接口对所有标准 Controller 生效。假设某 Controller 的 @RequestMapping 前缀为 /模块路径，则完整 URL = /apex-api + /模块路径 + 接口路径。

3.1 查询类¶

POST /list — 分页查询列表¶

通用获取列表，不传分页参数默认查询全部。

• 请求：BasicParamWrapper（见第二章）
• 响应：JsonResult<Page<ENTITY>>，records 为实体数组（snake_case）

POST /apex-api/bd/person/list
{ "current": 1, "size": 10 }

POST /listCommon — 分页查询（含上级数据）¶

同 /list，但携带所有上级公司的数据（跨公司查询场景）。自动加 @CommonData 数据权限。

POST /dict — 字典查询¶

按指定列查询数据做字典用。columns 指定返回列，支持 distinct。

POST /apex-api/bd/unit/dict
{
  "columns": ["id", "unit_name"],
  "andMap": { "enable_state": 1 }
}

• 响应：JsonResult<Object>（List）

POST /tree — 树形查询¶

查询树形结构数据（实体需实现 ITreeAble，如公司、部门、菜单）。

• 请求：BasicParamWrapper
• 响应：JsonResult<List<ENTITY>>，实体含 childs 子节点数组

POST /first — 取符合条件的第一条¶

• 请求：BasicParamWrapper
• 响应：JsonResult<ENTITY>

POST /last — 取符合条件的最后一条¶

• 请求：BasicParamWrapper
• 响应：JsonResult<ENTITY>

GET /getOne/{id} — 按 ID 查询¶

GET /apex-api/bd/person/getOne/1234567890

• 响应：JsonResult<ENTITY>

POST /listMap — 分页查询（返回 Map）¶

同 /list 但返回 Page<Dict>（动态 Map 结构），适合动态表格。

GET /getTableName — 获取表名¶

• 响应：JsonResult<Object>（当前实体对应的数据库表名）

3.2 写操作类（自动记录操作日志）¶

POST /saveOrUpdate — 保存或更新¶

传 id 即更新，不传 id 即新增。新增时 id 自动生成（雪花），created_by/created_time/updated_by/updated_time 自动填充。

• 请求：实体 JSON（属性用 snake_case 或 camelCase 均可）

POST /apex-api/bd/person/saveOrUpdate
{
  "id": "",                      // 空=新增；有值=更新
  "person_name": "张三",
  "dept_code": "D001",
  "corp_code": "C001"
}

• 响应：JsonResult<ENTITY>（返回带 id 的完整实体）
• 自动触发：序列号生成（@SequenceGenerator 字段）、重复校验（@CheckRepeat 字段）、JSR303 校验

POST /batchSaveOrUpdate — 批量保存更新¶

• 请求：实体数组

POST /apex-api/bd/person/batchSaveOrUpdate
[
  { "person_name": "张三" },
  { "person_name": "李四" }
]

• 响应：JsonResult<Object>

POST /delete/{id} — 按 ID 删除¶

POST /apex-api/bd/person/delete/1234567890

• 响应：JsonResult<String>

POST /batchDelete — 批量删除¶

• 请求：ID 数组

POST /apex-api/bd/person/batchDelete
["111", "222", "333"]

POST /deleteByParams — 按条件删除¶

• 请求：BasicParamWrapper（条件格式同查询）

POST /apex-api/bd/person/deleteByParams
{ "andMap": { "status": 9 } }

3.3 Map 动态操作类¶

不依赖实体结构的动态操作（前端字段动态的场景）。

POST /saveMap — Map 新增¶

• 请求：Dict（Map 结构，key=列名）

POST /apex-api/bd/person/saveMap
{ "person_name": "张三", "corp_code": "C001" }

POST /updateMap — Map 更新¶

同上（含 id 或按条件）。

POST /saveOrUpdateMap — Map 保存/更新¶

POST /batchSaveOrUpdateMap — 批量 Map 操作¶

• 请求：Map 数组

3.4 Excel 导入导出类¶

POST /exportToExcel — 导出 Excel¶

• 请求：TableData（动态表头 + 数据）

POST /apex-api/bd/person/exportToExcel
{
  "exportName": "人员列表",
  "tableHeaders": [
    { "columnName": "姓名", "columnKey": "person_name", "columnWidth": 120 },
    { "columnName": "部门", "columnKey": "dept_code", "dictCode": "dept_type" },
    { "columnName": "入职日期", "columnKey": "created_time", "datePattern": "yyyy-MM-dd" }
  ],
  "data": [ { "person_name": "张三", "dept_code": "D001", "created_time": "2026-08-01" } ],
  "headerColor": "#4384C7"
}

• 响应：文件流（浏览器直接下载）

TableHeader 表头字段：

POST /importExcelData — 导入 Excel¶

• 请求：multipart/form-data，字段名 file

const formData = new FormData();
formData.append('file', file);
axios.post('/apex-api/bd/person/importExcelData', formData);

• 响应：JsonResult<Object>
• 自动按实体 @ExcelProperty 映射，@ExcelUniqueColumn 去重

GET /generateTemplate — 下载导入模板¶

GET /apex-api/bd/person/generateTemplate

• 响应：Excel 文件流（含字典下拉列）

四、AI 快速调用指南¶

给前端 AI 助手的调用提示：

4.1 发现接口¶

任意标准模块的接口路径 = /apex-api + 模块路径 + 21 个标准路径之一。例如已知 /bd/person 是人员模块，则：

POST /apex-api/bd/person/list          ← 分页查询
POST /apex-api/bd/person/saveOrUpdate  ← 新增/更新
POST /apex-api/bd/person/delete/{id}   ← 删除
GET  /apex-api/bd/person/getOne/{id}   ← 按 id 查

4.2 完整调用序列（带登录态）¶

// 1. 登录拿 sessionid（⚠️ 登录接口参数是 form/query，不是 JSON body）
const loginRes = await axios.post(
  '/apex-api/dac/sysUser/auth/loginByPassword',
  'username=zhangsan&password=' + encodeURIComponent(rsaEncryptedPwd),
  { headers: { 'Content-Type': 'application/x-www-form-urlencoded' } }
);
const sessionId = loginRes.data.data.sessionId;

// 2. 后续请求带 sessionid header
axios.defaults.headers.common['sessionid'] = sessionId;

// 3. 分页查询
const list = await axios.post('/apex-api/bd/person/list', {
  current: 1, size: 10,
  andMap: { corp_code: 'C001' },
  orderBy: { created_time: 'desc' }
});

// 4. 判断成功
if (list.data.code === '200') {
  console.log(list.data.data.records);  // 数据
  console.log(list.data.data.total);    // 总数
}

4.3 常见坑¶

1. 响应是 snake_case：created_time 不是 createdTime（Jackson 全局 SNAKE_CASE 策略）
2. 条件 key 用数据库列名：andMap 的 key 是 corp_code 不是 corpCode
3. 不传分页 = 查全部：current/size 缺省时 size=MAX_VALUE，大数据表务必传 size
4. saveOrUpdate 靠 id 判断新增/更新：id 空字符串会被当新增
5. 登录接口是 form 参数：/dac/sysUser/auth/loginByPassword 用 query/form 传 username/password（RSA 加密兼容明文）
6. 业务模块的自定义接口：标准 21 个之外，各模块可能有扩展接口（见业务中台接口文档各分域页面）

五、各模块接口前缀速查¶

详细接口见 业务中台标准接口 各分域文档。

相关文档¶

• SDK开发包 — 后端 SDK 的 EnergyBaseController 实现
• 标准接口首页