用户信息入库系统 API 文档

项目简介

这是一个基于 Spring Boot 3.2.0 的动态用户信息入库系统，支持根据配置文件动态定义数据表字段，实现灵活的数据入库功能。

技术栈

• 框架: Spring Boot 3.2.0
• 数据库: MySQL 8.0.33
• ORM: MyBatis 3.0.3
• API文档: SpringDoc OpenAPI 2.1.0
• 构建工具: Maven

项目结构

src/main/java/com/xztech/
├── CreateUserInfoApplication.java    # 主启动类
├── common/                          # 公共类
│   ├── ApiResponse.java            # 统一响应格式
│   └── UserDataRequest.java        # 用户数据请求类
├── config/                         # 配置类
│   ├── CustomTableConfig.java      # 自定义表配置
│   └── OpenApiConfig.java          # OpenAPI配置
├── controller/                     # 控制器
│   └── UserInfoController.java     # 用户信息控制器
├── service/                       # 服务层
│   └── DynamicTableService.java    # 动态表服务
└── mapper/                        # 数据访问层
    └── DynamicTableMapper.java     # 动态表映射器

配置说明

数据库配置 (application.yml)

spring:
  datasource:
    url: jdbc:mysql://127.0.0.1:3309/workwear_check?useSSL=false&serverTimezone=UTC
    username: root
    password: root
    driver-class-name: com.mysql.cj.jdbc.Driver

server:
  port: 9090  # 服务端口

# 自定义数据表以及入库字段
custom:
  table-name: user_info_test        # 数据表名
  fields:                           # 字段列表
    - username
    - age
    - email
    - phone
    - name
    - address

API 接口文档

基础信息

• 服务地址: http://localhost:9090
• API文档: http://localhost:9090/index.html
• API文档JSON: http://localhost:9090/api-docs

1. 获取字段配置

接口描述: 获取当前配置的数据表字段列表

请求信息:

• URL: GET /api/userinfo/fields
• Content-Type: application/json

响应示例:

{
  "success": true,
  "message": "操作成功",
  "data": [
    "username",
    "age", 
    "email",
    "phone",
    "name",
    "address"
  ]
}

2. 添加用户信息

接口描述: 向配置的数据表中插入用户信息

请求信息:

• URL: POST /api/userinfo/add
• Content-Type: application/json

请求参数:

{
  "username": "张三",
  "age": 25,
  "email": "zhang@test.com",
  "phone": "13800138000",
  "name": "张三",
  "address": "北京市朝阳区"
}

参数说明:

• 所有字段必须与配置文件 custom.fields 中定义的字段完全匹配
• 字段名称区分大小写
• 不能包含配置文件中未定义的字段
• 不能缺少配置文件中定义的必需字段

成功响应示例:

{
  "success": true,
  "message": "操作完成",
  "data": "数据写入成功"
}

错误响应示例:

{
  "success": false,
  "message": "字段验证失败: 包含不允许的字段: invalid_field; 缺少必需字段: username",
  "data": null
}

错误码说明

错误类型	错误信息	说明
字段验证失败	包含不允许的字段	请求中包含配置文件中未定义的字段
字段验证失败	缺少必需字段	请求中缺少配置文件中定义的必需字段
系统错误	系统错误: [具体错误信息]	数据库连接、SQL执行等系统级错误

使用说明

1. 启动项目

# 编译项目
mvn clean compile

# 运行项目
mvn spring-boot:run

2. 配置数据表

在 application.yml 中配置数据表信息：

custom:
  table-name: your_table_name    # 替换为实际表名
  fields:                        # 配置表字段
    - field1
    - field2
    - field3

3. 创建数据表

根据配置的字段创建对应的MySQL数据表：

CREATE TABLE user_info_test (
    id INT AUTO_INCREMENT PRIMARY KEY,
    username VARCHAR(255),
    age INT,
    email VARCHAR(255),
    phone VARCHAR(20),
    name VARCHAR(255),
    address TEXT,
    create_time TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

4. 调用接口

1. 首先调用 GET /api/userinfo/fields 获取当前配置的字段列表
2. 根据返回的字段列表构建POST请求数据
3. 调用 POST /api/userinfo/add 插入数据

特性说明

动态字段验证

• 系统会根据配置文件中的字段定义进行严格验证
• 确保数据的一致性和完整性
• 防止无效字段的插入

统一响应格式

• 所有接口都使用统一的 ApiResponse<T> 响应格式
• 包含成功状态、消息和数据三个字段
• 便于前端统一处理响应结果

API文档自动生成

• 集成SpringDoc OpenAPI
• 自动生成Swagger UI文档
• 支持在线测试接口功能

注意事项

1. 字段匹配: 请求中的字段必须与配置文件中的字段完全匹配
2. 数据类型: 确保请求数据的数据类型与数据库字段类型兼容
3. 数据库连接: 确保MySQL服务正常运行，连接配置正确
4. 表结构: 确保数据表已创建且字段与配置一致

扩展说明

如需添加新的字段，请按以下步骤操作：

1. 在 application.yml 的 custom.fields 中添加新字段名
2. 在数据库表中添加对应的字段
3. 重启应用使配置生效
4. 调用 GET /api/userinfo/fields 确认字段已更新

版本信息

• 版本: 1.0.0
• 更新时间: 2025年
• 作者: moon