211 lines
4.3 KiB
Markdown
211 lines
4.3 KiB
Markdown
# 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响应格式：
|
||
|
||
```json
|
||
{
|
||
"status": 200,
|
||
"msg": "SUCCESS",
|
||
"data": {
|
||
// 具体数据
|
||
},
|
||
"traceId": "trace-id-value"
|
||
}
|
||
```
|
||
|
||
### 状态码说明
|
||
|
||
- **200**: 成功
|
||
- **400**: 请求参数错误
|
||
- **401**: 认证失败/未登录
|
||
- **403**: 权限不足
|
||
- **500**: 服务器内部错误
|
||
|
||
## 分页查询格式
|
||
|
||
分页查询请求参数：
|
||
```json
|
||
{
|
||
"pageNo": 1,
|
||
"pageSize": 10,
|
||
"params": {
|
||
// 查询参数
|
||
}
|
||
}
|
||
```
|
||
|
||
分页查询响应格式：
|
||
```json
|
||
{
|
||
"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](./authentication/登录认证API)
|
||
- [验证码API](./authentication/验证码API)
|
||
|
||
### 2. 用户管理模块 (User Management)
|
||
- [用户管理API](./user/用户管理API)
|
||
|
||
### 3. 权限管理模块 (Permission Management)
|
||
- [菜单管理API](./permission/菜单管理API)
|
||
- [角色管理API](./permission/角色管理API)
|
||
|
||
### 4. 系统管理模块 (System Management)
|
||
- [文件管理API](./system/文件管理API)
|
||
- [图片管理API](./system/图片管理API)
|
||
- [登录日志API](./system/登录日志API)
|
||
|
||
## 错误处理
|
||
|
||
系统提供了完善的错误处理机制：
|
||
|
||
### 常见错误类型
|
||
|
||
1. **业务异常**: 自定义业务逻辑错误
|
||
2. **认证异常**: 登录认证相关错误
|
||
3. **权限异常**: 权限验证失败
|
||
4. **参数异常**: 请求参数验证失败
|
||
5. **系统异常**: 服务器内部错误
|
||
|
||
### 错误响应格式
|
||
|
||
```json
|
||
{
|
||
"status": 400,
|
||
"msg": "具体错误信息",
|
||
"data": null,
|
||
"traceId": "trace-id-value"
|
||
}
|
||
```
|
||
|
||
## 开发环境配置
|
||
|
||
### 数据库配置
|
||
```yaml
|
||
spring:
|
||
datasource:
|
||
url: jdbc:mysql://localhost:3306/coder_common_thin
|
||
username: root
|
||
password: your_password
|
||
```
|
||
|
||
### Redis配置
|
||
```yaml
|
||
spring:
|
||
redis:
|
||
host: localhost
|
||
port: 6379
|
||
password: your_password
|
||
```
|
||
|
||
### Sa-Token配置
|
||
```yaml
|
||
sa-token:
|
||
token-name: Authorization
|
||
timeout: 2592000
|
||
activity-timeout: -1
|
||
is-concurrent: true
|
||
is-share: false
|
||
is-read-head: true
|
||
is-read-cookie: false
|
||
```
|
||
|
||
## 接口调用示例
|
||
|
||
### 登录接口调用
|
||
```bash
|
||
curl -X POST \
|
||
http://localhost:18099/auth/login \
|
||
-H 'Content-Type: application/json' \
|
||
-d '{
|
||
"loginName": "admin",
|
||
"password": "123456",
|
||
"codeKey": "uuid-key",
|
||
"securityCode": "1234"
|
||
}'
|
||
```
|
||
|
||
### 携带Token调用接口
|
||
```bash
|
||
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): 初始版本发布
|
||
|
||
## 联系方式
|
||
|
||
如有问题，请联系开发团队。 |