API 协议约定

Forge 后端所有接口遵循统一的响应格式和分页协议。你在设计新接口时必须遵守这些约定。

统一响应格式

所有接口返回 RespInfo 对象：

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

字段	类型	说明
code	Integer	状态码，200 成功，其他失败
msg	String	提示消息
data	Object	业务数据

后端使用方式：

// 成功返回
return RespInfo.success(data);

// 失败返回
return RespInfo.error("用户名已存在");

RESTful 路径

操作	方法	路径	示例
分页查询	GET	/module/page	GET /system/user/page
详情查询	GET	/module/:id	GET /system/user/1
新增	POST	/module	POST /system/user
修改	PUT	/module	PUT /system/user
删除	DELETE	/module/:id	DELETE /system/user/1

分页协议

请求参数

前端传递分页参数：

参数	类型	默认值	说明
pageNum	Integer	1	当前页码
pageSize	Integer	10	每页条数

后端 Controller 接收：

@GetMapping("/page")
public RespInfo page(
    @RequestParam(defaultValue = "1") Integer pageNum,
    @RequestParam(defaultValue = "10") Integer pageSize,
    SysUserDTO query
) {
    return RespInfo.success(userService.page(query, pageNum, pageSize));
}

响应格式

{
  "code": 200,
  "data": {
    "total": 100,
    "list": []
  }
}

API 加密

敏感接口使用 @ApiEncrypt / @ApiDecrypt 注解：

@PostMapping("/save")
@ApiDecrypt
@ApiEncrypt
public RespInfo save(@RequestBody UserDTO dto) {
    return RespInfo.success(userService.save(dto));
}

前端对应使用 postEncrypt 发送加密请求：

import { postEncrypt } from '@/utils/encrypt-request'

postEncrypt('/api/user/save', { name: '张三', phone: '13800138000' })

权限控制

使用 Sa-Token 注解控制接口权限：

@GetMapping("/list")
@SaCheckPermission("system:user:list")
public RespInfo list() {
    return RespInfo.success(userService.list());
}

前端 AiCrudPage 路径格式

AiCrudPage 的 api-config 中路径使用 METHOD@/path 格式，占位符用冒号 :id：

const apiConfig = {
  page: 'GET@/system/user/page',
  get: 'GET@/system/user/:id',
  add: 'POST@/system/user',
  edit: 'PUT@/system/user',
  delete: 'DELETE@/system/user/:id'
}