coder-thin-template-backend/api

Coder Common Thin Backend API 文档

项目概述

Coder Common Thin Backend 是一个基于Spring Boot 3.5.0的企业级开发框架，采用插件化架构设计，提供了完整的后台管理系统功能。

技术栈

• 后端框架: Spring Boot 3.5.0 + Java 17
• 数据库: MySQL 8 + MyBatis Plus 3.5.12
• 缓存: Redis (Spring Data Redis)
• 安全认证: Sa-Token 1.43.0
• 权限控制: RBAC (Role-Based Access Control)
• API文档: OpenAPI 3.0 (Swagger)
• 工具库: Hutool 5.8.38, Fastjson2 2.0.57, Guava 33.4.8

服务器信息

• 默认端口: 18099
• 基础URL: http://localhost:18099
• API前缀: /coder (除登录认证接口外)

认证方式

系统使用Sa-Token进行身份认证和权限管理：

• Token类型: Bearer Token
• Token位置: 请求头 Authorization 字段
• Token过期: 支持自定义过期时间
• 权限验证: 基于注解的权限验证

统一响应格式

所有接口均采用统一的JSON响应格式：

{
  "status": 200,
  "msg": "SUCCESS",
  "data": {
    // 具体数据
  },
  "traceId": "trace-id-value"
}

状态码说明

• 200: 成功
• 400: 请求参数错误
• 401: 认证失败/未登录
• 403: 权限不足
• 500: 服务器内部错误

分页查询格式

分页查询请求参数：

{
  "pageNo": 1,
  "pageSize": 10,
  "params": {
    // 查询参数
  }
}

分页查询响应格式：

{
  "status": 200,
  "msg": "SUCCESS",
  "data": {
    "records": [
      // 数据记录
    ],
    "total": 100,
    "size": 10,
    "current": 1,
    "pages": 10,
    "searchCount": true
  },
  "traceId": "trace-id-value"
}

权限系统

系统采用RBAC权限模型：

• 用户 (User): 系统使用者
• 角色 (Role): 权限的集合
• 权限 (Permission): 具体的操作权限
• 菜单 (Menu): 系统菜单和按钮权限

权限验证流程

1. 用户登录获取Token
2. 请求接口时携带Token
3. 系统验证Token有效性
4. 根据用户角色验证权限
5. 允许或拒绝访问

API模块分类

1. 认证模块 (Authentication)

• 登录认证API
• 验证码API

2. 用户管理模块 (User Management)

• 用户管理API

3. 权限管理模块 (Permission Management)

• 菜单管理API
• 角色管理API

4. 系统管理模块 (System Management)

• 文件管理API
• 图片管理API
• 登录日志API

错误处理

系统提供了完善的错误处理机制：

常见错误类型

1. 业务异常: 自定义业务逻辑错误
2. 认证异常: 登录认证相关错误
3. 权限异常: 权限验证失败
4. 参数异常: 请求参数验证失败
5. 系统异常: 服务器内部错误

错误响应格式

{
  "status": 400,
  "msg": "具体错误信息",
  "data": null,
  "traceId": "trace-id-value"
}

开发环境配置

数据库配置

spring:
  datasource:
    url: jdbc:mysql://localhost:3306/coder_common_thin
    username: root
    password: your_password

Redis配置

spring:
  redis:
    host: localhost
    port: 6379
    password: your_password

Sa-Token配置

sa-token:
  token-name: Authorization
  timeout: 2592000
  activity-timeout: -1
  is-concurrent: true
  is-share: false
  is-read-head: true
  is-read-cookie: false

接口调用示例

登录接口调用

curl -X POST \
  http://localhost:18099/auth/login \
  -H 'Content-Type: application/json' \
  -d '{
    "loginName": "admin",
    "password": "123456",
    "codeKey": "uuid-key",
    "securityCode": "1234"
  }'

携带Token调用接口

curl -X GET \
  http://localhost:18099/coder/sysLoginUser/getLoginUserInformation \
  -H 'Authorization: Bearer your-token-value'

注意事项

1. 所有接口都需要进行认证，除了登录接口和验证码接口
2. 权限验证基于角色和权限码进行
3. 系统支持多设备登录
4. 敏感操作会记录操作日志
5. 建议在生产环境中启用HTTPS

更新日志

• v1.0.0 (2025-07-05): 初始版本发布

联系方式

如有问题，请联系开发团队。