# 时钟项目后端代码库

**Repository Path**: shen19970101/clock-backend

## Basic Information

- **Project Name**: 时钟项目后端代码库
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-03
- **Last Updated**: 2026-04-03

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Clock Backend - 时钟应用后端服务

基于 Spring Boot 3.x 的高质量后端服务，提供用户认证和授权功能。

## 技术栈

- **框架**: Spring Boot 3.2.0
- **语言**: Java 17
- **构建工具**: Maven
- **数据库**: H2 (开发环境) / PostgreSQL (生产环境)
- **安全**: Spring Security + JWT
- **ORM**: Spring Data JPA

## 功能特性

- ✅ 用户注册
- ✅ 用户登录
- ✅ JWT Token 认证
- ✅ 密码加密 (BCrypt)
- ✅ 跨域支持 (CORS)
- ✅ 参数验证
- ✅ 全局异常处理
- ✅ 统一 API 响应格式

## 快速开始

### 环境要求

- JDK 17+
- Maven 3.6+

### 本地运行

1. **克隆项目**
   ```bash
   git clone <repository-url>
   cd clock-backend
   ```

2. **编译项目**
   ```bash
   mvn clean install
   ```

3. **运行应用**
   ```bash
   mvn spring-boot:run
   ```

4. **访问应用**
   - 服务地址: http://localhost:8083
   - H2 控制台: http://localhost:8083/h2-console
   - 健康检查: http://localhost:8083/api/auth/health

## API 文档

### 认证接口

#### 1. 用户注册

**请求**
```http
POST /api/auth/register
Content-Type: application/json

{
  "username": "testuser",
  "email": "test@example.com",
  "password": "password123",
  "confirmPassword": "password123"
}
```

**响应**
```json
{
  "success": true,
  "message": "注册成功",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "type": "Bearer",
    "userId": 1,
    "username": "testuser",
    "email": "test@example.com",
    "message": "注册成功"
  },
  "timestamp": 1234567890
}
```

#### 2. 用户登录

**请求**
```http
POST /api/auth/login
Content-Type: application/json

{
  "usernameOrEmail": "testuser",
  "password": "password123"
}
```

**响应**
```json
{
  "success": true,
  "message": "登录成功",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "type": "Bearer",
    "userId": 1,
    "username": "testuser",
    "email": "test@example.com",
    "message": "登录成功"
  },
  "timestamp": 1234567890
}
```

#### 3. 获取当前用户信息

**请求**
```http
GET /api/auth/me
Authorization: Bearer <token>
```

**响应**
```json
{
  "success": true,
  "message": "操作成功",
  "data": {
    "id": 1,
    "username": "testuser",
    "email": "test@example.com",
    "createdAt": "2024-01-01T00:00:00",
    "updatedAt": "2024-01-01T00:00:00",
    "lastLoginAt": "2024-01-01T00:00:00",
    "enabled": true
  },
  "timestamp": 1234567890
}
```

### 使用 Token 访问受保护接口

在请求头中添加 Authorization：

```http
Authorization: Bearer <your-jwt-token>
```

## 项目结构

```
clock-backend/
├── src/main/java/com/clock/
│   ├── ClockBackendApplication.java    # 主应用入口
│   ├── config/                          # 配置类
│   │   ├── SecurityConfig.java         # 安全配置
│   │   └── JwtAuthenticationFilter.java # JWT 过滤器
│   ├── controller/                      # 控制器
│   │   └── AuthController.java         # 认证控制器
│   ├── dto/                             # 数据传输对象
│   │   ├── ApiResponse.java            # 统一响应
│   │   ├── AuthResponse.java           # 认证响应
│   │   ├── LoginRequest.java           # 登录请求
│   │   └── RegisterRequest.java        # 注册请求
│   ├── entity/                          # 实体类
│   │   └── User.java                   # 用户实体
│   ├── exception/                       # 异常处理
│   │   ├── GlobalExceptionHandler.java # 全局异常处理
│   │   └── UserAlreadyExistsException.java
│   ├── repository/                      # 数据访问层
│   │   └── UserRepository.java
│   ├── service/                         # 服务层
│   │   └── UserService.java
│   └── util/                            # 工具类
│       ├── JwtUtil.java                # JWT 工具
│       └── PasswordUtil.java           # 密码工具
└── src/main/resources/
    └── application.yml                  # 配置文件
```

## 配置说明

### application.yml 主要配置

```yaml
server:
  port: 8083                    # 服务端口

jwt:
  secret: <your-secret-key>     # JWT 密钥
  expiration: 86400000          # Token 有效期 (24小时)

cors:
  allowed-origins: http://localhost:8082,http://localhost:3000
```

## 开发规范

### 代码质量

- ✅ 使用 Lombok 简化代码
- ✅ 参数验证使用 Jakarta Validation
- ✅ 统一的异常处理
- ✅ 清晰的日志记录
- ✅ RESTful API 设计

### 提交规范

```
feat: 新功能
fix: 修复bug
docs: 文档更新
style: 代码格式
refactor: 重构
test: 测试相关
chore: 构建/工具
```

## 与前端联调

### 前端配置

前端项目需要配置 API 地址：

```javascript
// api.js
const API_BASE_URL = 'http://localhost:8083/api/auth';

// 登录
export const login = (data) => axios.post(`${API_BASE_URL}/login`, data);

// 注册
export const register = (data) => axios.post(`${API_BASE_URL}/register`, data);
```

### Token 存储

```javascript
// 存储 Token
localStorage.setItem('token', response.data.data.token);

// 请求时携带 Token
axios.interceptors.request.use(config => {
  const token = localStorage.getItem('token');
  if (token) {
    config.headers.Authorization = `Bearer ${token}`;
  }
  return config;
});
```

## License

MIT