# xinling-backend

**Repository Path**: Eternal_CC/xinling-backend

## Basic Information

- **Project Name**: xinling-backend
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-06-06
- **Last Updated**: 2025-06-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 心灵港湾后端开发任务书

## 1. 项目概述

心灵港湾是一个集博客、树洞、时光邮局等功能于一体的综合性平台。后端采用Spring Boot框架开发，提供RESTful API接口服务。

## 2. 技术栈

### 2.1 核心框架
- Spring Boot 2.7.x
- Spring Security
- MyBatis
- MySQL 8.0
- Redis

### 2.2 工具库
- Lombok
- MapStruct
- JWT
- Swagger/OpenAPI
- Validation
- Commons Lang3
- MyBatis Generator
- PageHelper

### 2.3 开发工具
- Maven
- Git
- Postman
- IntelliJ IDEA

## 3. 项目结构

```
xinling-backend/
├── src/
│   ├── main/
│   │   ├── java/
│   │   │   └── com/xinling/
│   │   │       ├── XinlingApplication.java
│   │   │       ├── common/           # 通用组件
│   │   │       │   ├── api/         # 通用接口
│   │   │       │   │   ├── ResultCode.java    # 响应码枚举
│   │   │       │   │   └── ApiResult.java     # 通用响应体
│   │   │       │   ├── config/      # 通用配置
│   │   │       │   │   ├── MyBatisConfig.java
│   │   │       │   │   ├── RedisConfig.java
│   │   │       │   │   ├── SecurityConfig.java
│   │   │       │   │   ├── SwaggerConfig.java
│   │   │       │   │   └── WebMvcConfig.java
│   │   │       │   ├── exception/   # 通用异常
│   │   │       │   │   ├── GlobalExceptionHandler.java
│   │   │       │   │   ├── BusinessException.java
│   │   │       │   │   └── ResultCodeException.java
│   │   │       │   ├── util/        # 通用工具
│   │   │       │   │   ├── JwtUtil.java
│   │   │       │   │   ├── RedisUtil.java
│   │   │       │   │   ├── StringUtil.java
│   │   │       │   │   └── DateUtil.java
│   │   │       │   └── constant/    # 通用常量
│   │   │       │       ├── CommonConstant.java
│   │   │       │       └── SecurityConstant.java
│   │   │       ├── modules/         # 业务模块
│   │   │       │   ├── user/        # 用户模块
│   │   │       │   │   ├── controller/
│   │   │       │   │   ├── service/
│   │   │       │   │   │   ├── impl/
│   │   │       │   │   │   └── interfaces/
│   │   │       │   │   ├── mapper/
│   │   │       │   │   └── model/
│   │   │       │   │       ├── entity/
│   │   │       │   │       ├── dto/
│   │   │       │   │       └── vo/
│   │   │       │   ├── blog/        # 博客模块
│   │   │       │   │   ├── controller/
│   │   │       │   │   ├── service/
│   │   │       │   │   │   ├── impl/
│   │   │       │   │   │   └── interfaces/
│   │   │       │   │   ├── mapper/
│   │   │       │   │   └── model/
│   │   │       │   │       ├── entity/
│   │   │       │   │       ├── dto/
│   │   │       │   │       └── vo/
│   │   │       │   ├── treehole/    # 树洞模块
│   │   │       │   ├── timemail/    # 时光邮局模块
│   │   │       │   ├── game/        # 游戏模块
│   │   │       │   ├── timeline/    # 时间线模块
│   │   │       │   └── event/       # 活动模块
│   │   │       └── security/        # 安全相关
│   │   │           ├── JwtTokenProvider.java
│   │   │           ├── JwtAuthenticationFilter.java
│   │   │           └── UserDetailsServiceImpl.java
│   │   └── resources/
│   │       ├── mapper/              # MyBatis XML映射文件
│   │       │   ├── user/
│   │       │   ├── blog/
│   │       │   ├── treehole/
│   │       │   └── ...
│   │       ├── application.yml      # 主配置文件
│   │       ├── application-dev.yml  # 开发环境配置
│   │       └── application-prod.yml # 生产环境配置
│   └── test/                        # 测试代码
│       ├── java/
│       │   └── com/xinling/
│       │       ├── common/          # 通用组件测试
│       │       └── modules/         # 业务模块测试
│       └── resources/
│           └── test-application.yml
├── pom.xml                          # 项目依赖管理
└── README.md                        # 项目文档
```

## 4. 通用响应体设计

### 4.1 响应码枚举 (ResultCode.java)
```java
public enum ResultCode {
    SUCCESS(200, "操作成功"),
    FAILED(500, "操作失败"),
    VALIDATE_FAILED(404, "参数检验失败"),
    UNAUTHORIZED(401, "暂未登录或token已经过期"),
    FORBIDDEN(403, "没有相关权限"),
    
    // 用户相关错误码
    USER_NOT_EXIST(1001, "用户不存在"),
    USERNAME_OR_PASSWORD_ERROR(1002, "用户名或密码错误"),
    DUPLICATE_USERNAME(1003, "用户名已存在"),
    
    // 博客相关错误码
    POST_NOT_FOUND(2001, "文章不存在"),
    CATEGORY_NOT_FOUND(2002, "分类不存在"),
    
    // 树洞相关错误码
    MESSAGE_NOT_FOUND(3001, "消息不存在"),
    
    // 时光邮局相关错误码
    MAIL_NOT_FOUND(4001, "邮件不存在"),
    
    // 游戏相关错误码
    GAME_NOT_FOUND(5001, "游戏不存在"),
    
    // 时间线相关错误码
    EVENT_NOT_FOUND(6001, "事件不存在"),
    
    // 活动相关错误码
    EVENT_NOT_FOUND(7001, "活动不存在");

    private final int code;
    private final String message;

    ResultCode(int code, String message) {
        this.code = code;
        this.message = message;
    }

    public int getCode() {
        return code;
    }

    public String getMessage() {
        return message;
    }
}
```

### 4.2 通用响应体 (ApiResult.java)
```java
@Data
@NoArgsConstructor
@AllArgsConstructor
public class ApiResult<T> {
    private int code;
    private String message;
    private T data;
    private long timestamp;

    public ApiResult(int code, String message) {
        this.code = code;
        this.message = message;
        this.timestamp = System.currentTimeMillis();
    }

    public ApiResult(int code, String message, T data) {
        this.code = code;
        this.message = message;
        this.data = data;
        this.timestamp = System.currentTimeMillis();
    }

    public static <T> ApiResult<T> success() {
        return new ApiResult<>(ResultCode.SUCCESS.getCode(), ResultCode.SUCCESS.getMessage());
    }

    public static <T> ApiResult<T> success(T data) {
        return new ApiResult<>(ResultCode.SUCCESS.getCode(), ResultCode.SUCCESS.getMessage(), data);
    }

    public static <T> ApiResult<T> success(String message, T data) {
        return new ApiResult<>(ResultCode.SUCCESS.getCode(), message, data);
    }

    public static <T> ApiResult<T> failed() {
        return new ApiResult<>(ResultCode.FAILED.getCode(), ResultCode.FAILED.getMessage());
    }

    public static <T> ApiResult<T> failed(String message) {
        return new ApiResult<>(ResultCode.FAILED.getCode(), message);
    }

    public static <T> ApiResult<T> failed(ResultCode resultCode) {
        return new ApiResult<>(resultCode.getCode(), resultCode.getMessage());
    }

    public static <T> ApiResult<T> failed(ResultCode resultCode, String message) {
        return new ApiResult<>(resultCode.getCode(), message);
    }
}
```

### 4.3 业务异常 (BusinessException.java)
```java
public class BusinessException extends RuntimeException {
    private int code;
    private String message;

    public BusinessException(ResultCode resultCode) {
        this.code = resultCode.getCode();
        this.message = resultCode.getMessage();
    }

    public BusinessException(ResultCode resultCode, String message) {
        this.code = resultCode.getCode();
        this.message = message;
    }

    public int getCode() {
        return code;
    }

    @Override
    public String getMessage() {
        return message;
    }
}
```

### 4.4 全局异常处理 (GlobalExceptionHandler.java)
```java
@RestControllerAdvice
public class GlobalExceptionHandler {
    
    @ExceptionHandler(BusinessException.class)
    public ApiResult<Object> handleBusinessException(BusinessException e) {
        return ApiResult.failed(e.getCode(), e.getMessage());
    }

    @ExceptionHandler(MethodArgumentNotValidException.class)
    public ApiResult<Object> handleValidException(MethodArgumentNotValidException e) {
        BindingResult bindingResult = e.getBindingResult();
        String message = bindingResult.getFieldErrors().stream()
                .map(FieldError::getDefaultMessage)
                .collect(Collectors.joining(", "));
        return ApiResult.failed(ResultCode.VALIDATE_FAILED.getCode(), message);
    }

    @ExceptionHandler(Exception.class)
    public ApiResult<Object> handleException(Exception e) {
        return ApiResult.failed(ResultCode.FAILED.getCode(), e.getMessage());
    }
}
```

## 4. 模块划分

### 4.1 用户模块 (User)
- 用户注册
- 用户登录
- 用户信息管理
- 角色权限管理

### 4.2 博客模块 (Blog)
- 文章管理
- 分类管理
- 标签管理
- 评论管理

### 4.3 树洞模块 (Treehole)
- 匿名消息发布
- 消息列表
- 支持功能
- 消息管理

### 4.4 时光邮局模块 (TimeMail)
- 写信功能
- 邮件管理
- 定时发送
- 邮件状态追踪

### 4.5 游戏模块 (Game)
- 游戏记录
- 分数统计
- 排行榜

### 4.6 时间线模块 (Timeline)
- 事件管理
- 时间线展示
- 图片管理

### 4.7 活动模块 (Event)
- 活动管理
- 报名功能
- 参与统计

## 5. API设计规范

### 5.1 接口命名
- 使用RESTful风格
- URL使用小写字母
- 使用连字符(-)分隔单词
- 使用复数形式表示资源集合

### 5.2 请求方法
- GET：查询资源
- POST：创建资源
- PUT：更新资源
- DELETE：删除资源
- PATCH：部分更新

### 5.3 响应格式
```json
{
    "code": 200,
    "message": "success",
    "data": {}
}
```

### 5.4 状态码
- 200：成功
- 400：请求错误
- 401：未授权
- 403：禁止访问
- 404：资源不存在
- 500：服务器错误

## 6. 安全设计

### 6.1 认证
- JWT token认证
- 密码加密存储
- 登录失败限制

### 6.2 授权
- 基于角色的访问控制
- 接口权限控制
- 数据权限控制

### 6.3 数据安全
- 敏感数据加密
- SQL注入防护
- XSS防护
- CSRF防护

## 7. 缓存设计

### 7.1 缓存策略
- 热点数据缓存
- 查询结果缓存
- 计数器缓存

### 7.2 缓存更新
- 定时更新
- 主动更新
- 被动更新

## 8. 开发规范

### 8.1 代码规范
- 遵循阿里巴巴Java开发手册
- 使用统一的代码格式化工具
- 编写完整的注释文档

### 8.2 提交规范
- feat: 新功能
- fix: 修复bug
- docs: 文档更新
- style: 代码格式
- refactor: 重构
- test: 测试
- chore: 构建过程或辅助工具的变动

### 8.3 测试规范
- 单元测试覆盖率>80%
- 接口测试用例完整
- 性能测试达标

## 9. 部署方案

### 9.1 环境要求
- JDK 1.8+
- MySQL 8.0+
- Redis 6.0+
- Maven 3.6+

### 9.2 部署步骤
1. 环境准备
2. 数据库初始化
3. 配置文件修改
4. 打包部署
5. 服务启动

## 10. 监控方案

### 10.1 系统监控
- 服务器监控
- 应用监控
- 数据库监控

### 10.2 业务监控
- 接口调用量
- 响应时间
- 错误率
- 用户行为

## 11. 开发计划

### 第一阶段：基础架构搭建（1周）
- 项目初始化
- 数据库设计
- 基础框架搭建
- 安全框架集成

### 第二阶段：核心功能开发（2周）
- 用户模块
- 博客模块
- 树洞模块
- 时光邮局模块

### 第三阶段：扩展功能开发（1周）
- 游戏模块
- 时间线模块
- 活动模块

### 第四阶段：测试优化（1周）
- 单元测试
- 接口测试
- 性能优化
- 文档完善

## 12. 注意事项

1. 代码提交前进行自测
2. 保持代码简洁清晰
3. 及时更新文档
4. 做好版本控制
5. 注意数据安全
6. 保持良好沟通

## 13. 联系方式

- 项目负责人：[姓名]
- 邮箱：[邮箱地址]
- 电话：[电话号码]