DeepSeek-接口设计

1、前言

AI时代的到来，推动着各行各业的革新与重新洗牌，那么对软件开发行业来说，AI的出现也带来了全新的机遇与挑战，那些不会借助于AI工具提高开发效率的程序员终会给时代淘汰。

2、接口设计

用户管理系统 RESTful 接口文档（完整版）

1. 用户管理接口

1.1 用户分页查询

GET /api/users
请求参数：

参数名	类型	是否必须	示例	说明
department_id	integer	否	1	部门ID
username	string	否	admin	用户名（模糊查询）
phone	string	否	15888888888	手机号（精确匹配）
status	string	否	active	状态（active/inactive）
start_time	string	否	2024-06-01 00:00:00	创建时间起始
end_time	string	否	2024-06-30 23:59:59	创建时间截止
page	integer	是	1	当前页码（默认1）
page_size	integer	是	10	每页条数（默认10）

响应示例：

json 复制代码

{
  "code": 200,
  "data": {
    "total": 2,
    "rows": [
      {
        "user_id": 1,
        "username": "admin",
        "nickname": "若依",
        "department_name": "研发部门",
        "phone": "15888888888",
        "status": "active",
        "created_at": "2024-06-30 11:27:11"
      },
      {
        "user_id": 2,
        "username": "ry",
        "nickname": "若依",
        "department_name": "测试部门",
        "phone": "15666666666",
        "status": "active",
        "created_at": "2024-06-30 11:27:11"
      }
    ]
  }
}

1.2 创建用户

POST /api/users
请求体：

json 复制代码

{
  "username": "new_user",
  "nickname": "新用户",
  "department_id": 1,
  "phone": "13123456789",
  "status": "active"
}

校验规则：

用户名唯一（冲突返回 HTTP 409）
手机号唯一（冲突返回 HTTP 409）

1.3 修改用户

PUT /api/users/{user_id}
请求体：

json 复制代码

{
  "nickname": "修改后的昵称",
  "department_id": 2,
  "phone": "13123456789",
  "status": "inactive"
}

1.4 删除用户

DELETE /api/users/{user_id}

1.5 用户详情查询

GET /api/users/{user_id}
响应示例：

json 复制代码

{
  "code": 200,
  "data": {
    "user_id": 1,
    "username": "admin",
    "nickname": "若依",
    "department_id": 1,
    "department_name": "研发部门",
    "phone": "15888888888",
    "status": "active",
    "created_at": "2024-06-30 11:27:11"
  }
}

1.6 导出用户

GET /api/users/export
参数：同分页查询接口
响应：直接返回 Excel 文件流

2. 部门管理接口

2.1 部门树形结构查询

GET /api/depts/tree
响应示例：

json 复制代码

{
  "code": 200,
  "data": [
    {
      "department_id": 1,
      "department_name": "深圳总公司",
      "children": [
        {
          "department_id": 2,
          "department_name": "研发部门"
        },
        {
          "department_id": 3,
          "department_name": "市场部门"
        }
      ]
    }
  ]
}

2.2 创建部门

POST /api/depts
请求体：

json 复制代码

{
  "department_name": "新部门",
  "parent_id": 1  // 可为 null（顶级部门）
}

2.3 修改部门

PUT /api/depts/{department_id}
请求体：

json 复制代码

{
  "department_name": "更新后的部门名称"
}

2.4 删除部门

DELETE /api/depts/{department_id}
校验规则：

若部门下存在子部门或用户，禁止删除（返回 HTTP 400）

3. 数据字典

状态枚举 ：active（启用）、inactive（禁用）
HTTP 状态码 ：
- 200：操作成功
- 400：请求参数错误
- 404：资源不存在
- 409：唯一性冲突（用户名/手机号/部门名称）
- 500：服务器内部错误

接口设计说明

RESTful 资源命名 ：
- 用户资源：/api/users
- 部门资源：/api/depts
关联查询 ：用户列表返回 department_name 字段，需关联部门表查询
分页标准化 ：分页参数统一命名为 page 和 page_size
文件操作 ：导出接口直接返回文件流，前端通过 Content-Disposition 处理文件名

本接口文档严格遵循原型功能及数据库设计，确保与用户管理系统的业务逻辑和数据结构完全一致。