fix
This commit is contained in:
xujiang
955
backend-old/docs/CLAUDE.md
Normal file
955
backend-old/docs/CLAUDE.md
Normal file
@ -0,0 +1,955 @@
|
||||
# Documentation Module - CLAUDE.md
|
||||
|
||||
本文件为 Claude Code 在文档模块中工作时提供指导。
|
||||
|
||||
## 🎯 模块概览
|
||||
|
||||
文档模块负责维护项目的技术文档、API 文档和架构设计文档，确保项目的可理解性和可维护性。
|
||||
|
||||
### 主要职责
|
||||
- 📚 API 接口文档
|
||||
- 🏗️ 架构设计文档
|
||||
- 🚀 部署运维文档
|
||||
- 📖 开发者指南
|
||||
- 📋 变更日志
|
||||
|
||||
## 📁 模块结构
|
||||
|
||||
```
|
||||
docs/
|
||||
├── CLAUDE.md # 📋 当前文件 - API 文档和接口设计指导
|
||||
├── api/ # 📚 API 接口文档
|
||||
│ ├── openapi.yaml # OpenAPI 3.0 规范
|
||||
│ ├── swagger.json # Swagger JSON 格式
|
||||
│ ├── postman/ # Postman 集合
|
||||
│ │ ├── photography.json # API 测试集合
|
||||
│ │ └── environment.json # 环境变量
|
||||
│ └── examples/ # 请求响应示例
|
||||
│ ├── user_examples.md # 用户接口示例
|
||||
│ ├── photo_examples.md # 照片接口示例
|
||||
│ └── auth_examples.md # 认证接口示例
|
||||
├── architecture/ # 🏗️ 架构设计文档
|
||||
│ ├── overview.md # 系统架构概览
|
||||
│ ├── database_design.md # 数据库设计
|
||||
│ ├── api_design.md # API 设计原则
|
||||
│ ├── security.md # 安全架构
|
||||
│ └── performance.md # 性能优化
|
||||
├── development/ # 👨💻 开发文档
|
||||
│ ├── getting_started.md # 快速开始
|
||||
│ ├── coding_standards.md # 编码规范
|
||||
│ ├── testing_guide.md # 测试指南
|
||||
│ ├── debugging.md # 调试指南
|
||||
│ └── contribution.md # 贡献指南
|
||||
├── deployment/ # 🚀 部署文档
|
||||
│ ├── local_deployment.md # 本地部署
|
||||
│ ├── docker_deployment.md # Docker 部署
|
||||
│ ├── production_deployment.md # 生产环境部署
|
||||
│ ├── monitoring.md # 监控配置
|
||||
│ └── troubleshooting.md # 故障排查
|
||||
├── guides/ # 📖 使用指南
|
||||
│ ├── user_management.md # 用户管理
|
||||
│ ├── photo_management.md # 照片管理
|
||||
│ ├── authentication.md # 认证授权
|
||||
│ └── file_upload.md # 文件上传
|
||||
├── changelog/ # 📋 变更日志
|
||||
│ ├── CHANGELOG.md # 版本变更记录
|
||||
│ └── migration_guides/ # 迁移指南
|
||||
│ ├── v1_to_v2.md # 版本迁移
|
||||
│ └── breaking_changes.md # 破坏性变更
|
||||
└── templates/ # 📄 文档模板
|
||||
├── api_template.md # API 文档模板
|
||||
├── guide_template.md # 指南模板
|
||||
└── adr_template.md # 架构决策记录模板
|
||||
```
|
||||
|
||||
## 📚 API 文档
|
||||
|
||||
### OpenAPI 3.0 规范
|
||||
```yaml
|
||||
# api/openapi.yaml - OpenAPI 3.0 规范
|
||||
openapi: 3.0.3
|
||||
info:
|
||||
title: Photography Portfolio API
|
||||
description: 摄影作品集 REST API
|
||||
version: 1.0.0
|
||||
contact:
|
||||
name: API Support
|
||||
email: support@photography.com
|
||||
license:
|
||||
name: MIT
|
||||
url: https://opensource.org/licenses/MIT
|
||||
|
||||
servers:
|
||||
- url: https://api.photography.com/v1
|
||||
description: 生产环境
|
||||
- url: https://staging-api.photography.com/v1
|
||||
description: 测试环境
|
||||
- url: http://localhost:8080/api/v1
|
||||
description: 开发环境
|
||||
|
||||
paths:
|
||||
/users:
|
||||
get:
|
||||
summary: 获取用户列表
|
||||
description: 获取系统中的用户列表，支持分页和过滤
|
||||
operationId: listUsers
|
||||
tags:
|
||||
- Users
|
||||
parameters:
|
||||
- name: page
|
||||
in: query
|
||||
description: 页码
|
||||
required: false
|
||||
schema:
|
||||
type: integer
|
||||
minimum: 1
|
||||
default: 1
|
||||
- name: limit
|
||||
in: query
|
||||
description: 每页数量
|
||||
required: false
|
||||
schema:
|
||||
type: integer
|
||||
minimum: 1
|
||||
maximum: 100
|
||||
default: 20
|
||||
- name: sort
|
||||
in: query
|
||||
description: 排序字段
|
||||
required: false
|
||||
schema:
|
||||
type: string
|
||||
enum: [id, username, email, created_at]
|
||||
default: created_at
|
||||
- name: order
|
||||
in: query
|
||||
description: 排序方向
|
||||
required: false
|
||||
schema:
|
||||
type: string
|
||||
enum: [asc, desc]
|
||||
default: desc
|
||||
responses:
|
||||
'200':
|
||||
description: 成功获取用户列表
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/UserListResponse'
|
||||
'400':
|
||||
description: 请求参数错误
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ErrorResponse'
|
||||
'401':
|
||||
description: 未授权
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ErrorResponse'
|
||||
'500':
|
||||
description: 服务器内部错误
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ErrorResponse'
|
||||
security:
|
||||
- BearerAuth: []
|
||||
|
||||
post:
|
||||
summary: 创建用户
|
||||
description: 创建新用户账户
|
||||
operationId: createUser
|
||||
tags:
|
||||
- Users
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/CreateUserRequest'
|
||||
responses:
|
||||
'201':
|
||||
description: 用户创建成功
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/UserResponse'
|
||||
'400':
|
||||
description: 请求参数错误
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ValidationErrorResponse'
|
||||
'409':
|
||||
description: 用户已存在
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ErrorResponse'
|
||||
|
||||
/users/{id}:
|
||||
get:
|
||||
summary: 获取用户详情
|
||||
description: 根据用户ID获取用户详细信息
|
||||
operationId: getUserById
|
||||
tags:
|
||||
- Users
|
||||
parameters:
|
||||
- name: id
|
||||
in: path
|
||||
description: 用户ID
|
||||
required: true
|
||||
schema:
|
||||
type: integer
|
||||
format: int64
|
||||
responses:
|
||||
'200':
|
||||
description: 成功获取用户信息
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/UserResponse'
|
||||
'404':
|
||||
description: 用户不存在
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ErrorResponse'
|
||||
security:
|
||||
- BearerAuth: []
|
||||
|
||||
components:
|
||||
schemas:
|
||||
User:
|
||||
type: object
|
||||
properties:
|
||||
id:
|
||||
type: integer
|
||||
format: int64
|
||||
description: 用户ID
|
||||
example: 1
|
||||
username:
|
||||
type: string
|
||||
description: 用户名
|
||||
example: "john_doe"
|
||||
email:
|
||||
type: string
|
||||
format: email
|
||||
description: 邮箱地址
|
||||
example: "john@example.com"
|
||||
first_name:
|
||||
type: string
|
||||
description: 名字
|
||||
example: "John"
|
||||
last_name:
|
||||
type: string
|
||||
description: 姓氏
|
||||
example: "Doe"
|
||||
avatar:
|
||||
type: string
|
||||
format: uri
|
||||
description: 头像URL
|
||||
example: "https://example.com/avatars/john.jpg"
|
||||
role:
|
||||
type: string
|
||||
enum: [admin, editor, user]
|
||||
description: 用户角色
|
||||
example: "user"
|
||||
status:
|
||||
type: string
|
||||
enum: [active, inactive, banned]
|
||||
description: 用户状态
|
||||
example: "active"
|
||||
created_at:
|
||||
type: string
|
||||
format: date-time
|
||||
description: 创建时间
|
||||
example: "2024-01-01T00:00:00Z"
|
||||
updated_at:
|
||||
type: string
|
||||
format: date-time
|
||||
description: 更新时间
|
||||
example: "2024-01-01T00:00:00Z"
|
||||
required:
|
||||
- id
|
||||
- username
|
||||
- email
|
||||
- role
|
||||
- status
|
||||
- created_at
|
||||
- updated_at
|
||||
|
||||
CreateUserRequest:
|
||||
type: object
|
||||
properties:
|
||||
username:
|
||||
type: string
|
||||
minLength: 3
|
||||
maxLength: 50
|
||||
pattern: '^[a-zA-Z0-9_-]+$'
|
||||
description: 用户名
|
||||
example: "john_doe"
|
||||
email:
|
||||
type: string
|
||||
format: email
|
||||
description: 邮箱地址
|
||||
example: "john@example.com"
|
||||
password:
|
||||
type: string
|
||||
minLength: 8
|
||||
description: 密码
|
||||
example: "SecurePassword123!"
|
||||
first_name:
|
||||
type: string
|
||||
maxLength: 50
|
||||
description: 名字
|
||||
example: "John"
|
||||
last_name:
|
||||
type: string
|
||||
maxLength: 50
|
||||
description: 姓氏
|
||||
example: "Doe"
|
||||
required:
|
||||
- username
|
||||
- email
|
||||
- password
|
||||
|
||||
UserResponse:
|
||||
type: object
|
||||
properties:
|
||||
success:
|
||||
type: boolean
|
||||
example: true
|
||||
data:
|
||||
$ref: '#/components/schemas/User'
|
||||
message:
|
||||
type: string
|
||||
example: "User retrieved successfully"
|
||||
timestamp:
|
||||
type: integer
|
||||
format: int64
|
||||
example: 1704067200
|
||||
request_id:
|
||||
type: string
|
||||
example: "req_123456789"
|
||||
|
||||
UserListResponse:
|
||||
type: object
|
||||
properties:
|
||||
success:
|
||||
type: boolean
|
||||
example: true
|
||||
data:
|
||||
type: array
|
||||
items:
|
||||
$ref: '#/components/schemas/User'
|
||||
pagination:
|
||||
$ref: '#/components/schemas/Pagination'
|
||||
message:
|
||||
type: string
|
||||
example: "Users retrieved successfully"
|
||||
timestamp:
|
||||
type: integer
|
||||
format: int64
|
||||
example: 1704067200
|
||||
request_id:
|
||||
type: string
|
||||
example: "req_123456789"
|
||||
|
||||
Pagination:
|
||||
type: object
|
||||
properties:
|
||||
page:
|
||||
type: integer
|
||||
example: 1
|
||||
limit:
|
||||
type: integer
|
||||
example: 20
|
||||
total:
|
||||
type: integer
|
||||
format: int64
|
||||
example: 100
|
||||
total_pages:
|
||||
type: integer
|
||||
example: 5
|
||||
has_next:
|
||||
type: boolean
|
||||
example: true
|
||||
has_prev:
|
||||
type: boolean
|
||||
example: false
|
||||
|
||||
ErrorResponse:
|
||||
type: object
|
||||
properties:
|
||||
success:
|
||||
type: boolean
|
||||
example: false
|
||||
error:
|
||||
$ref: '#/components/schemas/Error'
|
||||
timestamp:
|
||||
type: integer
|
||||
format: int64
|
||||
example: 1704067200
|
||||
request_id:
|
||||
type: string
|
||||
example: "req_123456789"
|
||||
|
||||
Error:
|
||||
type: object
|
||||
properties:
|
||||
code:
|
||||
type: string
|
||||
example: "USER_NOT_FOUND"
|
||||
message:
|
||||
type: string
|
||||
example: "User not found"
|
||||
details:
|
||||
type: string
|
||||
example: "User with ID 123 does not exist"
|
||||
|
||||
ValidationErrorResponse:
|
||||
type: object
|
||||
properties:
|
||||
success:
|
||||
type: boolean
|
||||
example: false
|
||||
error:
|
||||
type: object
|
||||
properties:
|
||||
code:
|
||||
type: string
|
||||
example: "VALIDATION_ERROR"
|
||||
message:
|
||||
type: string
|
||||
example: "Validation failed"
|
||||
details:
|
||||
type: array
|
||||
items:
|
||||
$ref: '#/components/schemas/ValidationError'
|
||||
timestamp:
|
||||
type: integer
|
||||
format: int64
|
||||
example: 1704067200
|
||||
request_id:
|
||||
type: string
|
||||
example: "req_123456789"
|
||||
|
||||
ValidationError:
|
||||
type: object
|
||||
properties:
|
||||
field:
|
||||
type: string
|
||||
example: "email"
|
||||
value:
|
||||
type: string
|
||||
example: "invalid-email"
|
||||
tag:
|
||||
type: string
|
||||
example: "email"
|
||||
message:
|
||||
type: string
|
||||
example: "email must be a valid email address"
|
||||
|
||||
securitySchemes:
|
||||
BearerAuth:
|
||||
type: http
|
||||
scheme: bearer
|
||||
bearerFormat: JWT
|
||||
description: JWT Bearer token
|
||||
|
||||
parameters:
|
||||
PageParam:
|
||||
name: page
|
||||
in: query
|
||||
description: 页码
|
||||
required: false
|
||||
schema:
|
||||
type: integer
|
||||
minimum: 1
|
||||
default: 1
|
||||
|
||||
LimitParam:
|
||||
name: limit
|
||||
in: query
|
||||
description: 每页数量
|
||||
required: false
|
||||
schema:
|
||||
type: integer
|
||||
minimum: 1
|
||||
maximum: 100
|
||||
default: 20
|
||||
|
||||
SortParam:
|
||||
name: sort
|
||||
in: query
|
||||
description: 排序字段
|
||||
required: false
|
||||
schema:
|
||||
type: string
|
||||
default: "created_at"
|
||||
|
||||
OrderParam:
|
||||
name: order
|
||||
in: query
|
||||
description: 排序方向
|
||||
required: false
|
||||
schema:
|
||||
type: string
|
||||
enum: [asc, desc]
|
||||
default: "desc"
|
||||
|
||||
tags:
|
||||
- name: Users
|
||||
description: 用户管理接口
|
||||
- name: Photos
|
||||
description: 照片管理接口
|
||||
- name: Authentication
|
||||
description: 认证授权接口
|
||||
- name: Categories
|
||||
description: 分类管理接口
|
||||
- name: Tags
|
||||
description: 标签管理接口
|
||||
```
|
||||
|
||||
## 🏗️ 架构设计
|
||||
|
||||
### 系统架构概览
|
||||
```markdown
|
||||
# architecture/overview.md - 系统架构概览
|
||||
|
||||
## 整体架构
|
||||
|
||||
Photography Portfolio 采用现代化的微服务架构，基于 Go 语言开发，使用 Clean Architecture 设计模式。
|
||||
|
||||
### 架构层次
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ Frontend Layer │
|
||||
│ Next.js + React + TypeScript + Tailwind CSS │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
│ HTTP/HTTPS
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ API Gateway │
|
||||
│ Caddy + Load Balancer │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
│ HTTP
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ Backend Services │
|
||||
│ │
|
||||
│ ┌─────────────────┐ ┌─────────────────┐ ┌───────────────┐ │
|
||||
│ │ User Service │ │ Photo Service │ │ Auth Service │ │
|
||||
│ │ (Go + Gin) │ │ (Go + Gin) │ │ (Go + Gin) │ │
|
||||
│ └─────────────────┘ └─────────────────┘ └───────────────┘ │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
│ SQL/NoSQL
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ Data Layer │
|
||||
│ │
|
||||
│ ┌─────────────────┐ ┌─────────────────┐ ┌───────────────┐ │
|
||||
│ │ PostgreSQL │ │ Redis │ │ File Storage │ │
|
||||
│ │ (主数据库) │ │ (缓存) │ │ (S3/Local) │ │
|
||||
│ └─────────────────┘ └─────────────────┘ └───────────────┘ │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### 核心设计原则
|
||||
|
||||
1. **单一职责原则**: 每个服务只负责一个业务领域
|
||||
2. **依赖倒置原则**: 高层模块不依赖低层模块，都依赖抽象
|
||||
3. **接口隔离原则**: 使用接口定义契约，便于测试和替换
|
||||
4. **开闭原则**: 对扩展开放，对修改封闭
|
||||
5. **最小知识原则**: 模块间耦合度最小化
|
||||
|
||||
### 技术栈选择
|
||||
|
||||
#### 后端技术栈
|
||||
- **语言**: Go 1.23+ (性能优异，并发支持)
|
||||
- **框架**: Gin (轻量级，高性能 HTTP 框架)
|
||||
- **数据库**: PostgreSQL (关系型数据，事务支持)
|
||||
- **缓存**: Redis (高性能内存缓存)
|
||||
- **ORM**: GORM (功能丰富，性能优良)
|
||||
- **认证**: JWT (无状态，扩展性好)
|
||||
- **日志**: Uber Zap (结构化，高性能)
|
||||
- **配置**: Viper (灵活的配置管理)
|
||||
|
||||
#### 部署技术栈
|
||||
- **容器化**: Docker + Docker Compose
|
||||
- **Web 服务器**: Caddy (自动 HTTPS，配置简单)
|
||||
- **CI/CD**: Gitea Actions (自动化部署)
|
||||
- **监控**: Prometheus + Grafana (可观测性)
|
||||
|
||||
### 数据流向
|
||||
|
||||
1. **请求流程**:
|
||||
Frontend → API Gateway → Backend Service → Repository → Database
|
||||
|
||||
2. **响应流程**:
|
||||
Database → Repository → Service → Handler → API Gateway → Frontend
|
||||
|
||||
3. **认证流程**:
|
||||
Client → Auth Service → JWT Token → Protected Resources
|
||||
|
||||
4. **文件上传流程**:
|
||||
Client → Upload Handler → Storage Service → File System/S3
|
||||
```
|
||||
|
||||
### 数据库设计
|
||||
```markdown
|
||||
# architecture/database_design.md - 数据库设计
|
||||
|
||||
## 数据库选择
|
||||
|
||||
### PostgreSQL (主数据库)
|
||||
- **优势**: ACID 事务支持，丰富的数据类型，成熟的生态
|
||||
- **用途**: 用户数据、照片元数据、分类标签等结构化数据
|
||||
- **版本**: PostgreSQL 14+
|
||||
|
||||
### Redis (缓存数据库)
|
||||
- **优势**: 高性能内存存储，丰富的数据结构
|
||||
- **用途**: 会话缓存、频繁查询数据缓存、限流计数器
|
||||
- **版本**: Redis 6+
|
||||
|
||||
## 表结构设计
|
||||
|
||||
### 用户表 (users)
|
||||
```sql
|
||||
CREATE TABLE users (
|
||||
id BIGSERIAL PRIMARY KEY,
|
||||
username VARCHAR(50) UNIQUE NOT NULL,
|
||||
email VARCHAR(100) UNIQUE NOT NULL,
|
||||
password VARCHAR(255) NOT NULL,
|
||||
first_name VARCHAR(50),
|
||||
last_name VARCHAR(50),
|
||||
avatar VARCHAR(255),
|
||||
bio TEXT,
|
||||
role VARCHAR(20) DEFAULT 'user',
|
||||
status VARCHAR(20) DEFAULT 'active',
|
||||
last_login_at TIMESTAMP,
|
||||
email_verified_at TIMESTAMP,
|
||||
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
|
||||
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
|
||||
deleted_at TIMESTAMP
|
||||
);
|
||||
|
||||
-- 索引
|
||||
CREATE INDEX idx_users_email ON users(email);
|
||||
CREATE INDEX idx_users_username ON users(username);
|
||||
CREATE INDEX idx_users_status ON users(status);
|
||||
CREATE INDEX idx_users_created_at ON users(created_at);
|
||||
```
|
||||
|
||||
### 照片表 (photos)
|
||||
```sql
|
||||
CREATE TABLE photos (
|
||||
id BIGSERIAL PRIMARY KEY,
|
||||
user_id BIGINT NOT NULL REFERENCES users(id) ON DELETE CASCADE,
|
||||
title VARCHAR(255) NOT NULL,
|
||||
description TEXT,
|
||||
filename VARCHAR(255) NOT NULL,
|
||||
file_path VARCHAR(500) NOT NULL,
|
||||
file_size BIGINT NOT NULL,
|
||||
mime_type VARCHAR(100) NOT NULL,
|
||||
width INTEGER DEFAULT 0,
|
||||
height INTEGER DEFAULT 0,
|
||||
exif_data TEXT,
|
||||
taken_at TIMESTAMP,
|
||||
location VARCHAR(255),
|
||||
camera VARCHAR(100),
|
||||
lens VARCHAR(100),
|
||||
status VARCHAR(20) DEFAULT 'active',
|
||||
view_count INTEGER DEFAULT 0,
|
||||
download_count INTEGER DEFAULT 0,
|
||||
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
|
||||
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
|
||||
deleted_at TIMESTAMP
|
||||
);
|
||||
|
||||
-- 索引
|
||||
CREATE INDEX idx_photos_user_id ON photos(user_id);
|
||||
CREATE INDEX idx_photos_status ON photos(status);
|
||||
CREATE INDEX idx_photos_created_at ON photos(created_at);
|
||||
CREATE INDEX idx_photos_taken_at ON photos(taken_at);
|
||||
```
|
||||
|
||||
## 关系设计
|
||||
|
||||
### 实体关系图
|
||||
```
|
||||
Users ||--o{ Photos : owns
|
||||
Photos }o--o{ Categories : categorized_by
|
||||
Photos }o--o{ Tags : tagged_with
|
||||
Users ||--o{ Albums : creates
|
||||
Albums }o--o{ Photos : contains
|
||||
```
|
||||
|
||||
### 外键约束
|
||||
- 所有外键使用 CASCADE 删除策略
|
||||
- 确保数据一致性和完整性
|
||||
- 使用索引优化查询性能
|
||||
|
||||
## 查询优化
|
||||
|
||||
### 索引策略
|
||||
1. **主键索引**: 自动创建
|
||||
2. **外键索引**: 手动创建，优化关联查询
|
||||
3. **查询索引**: 根据常用查询条件创建
|
||||
4. **复合索引**: 针对多字段查询优化
|
||||
|
||||
### 查询优化技巧
|
||||
1. **避免 N+1 查询**: 使用预加载
|
||||
2. **分页查询**: 使用 LIMIT 和 OFFSET
|
||||
3. **条件筛选**: 在数据库层面过滤数据
|
||||
4. **结果缓存**: 缓存频繁查询的结果
|
||||
```
|
||||
|
||||
## 📖 开发指南
|
||||
|
||||
### 快速开始
|
||||
```markdown
|
||||
# development/getting_started.md - 快速开始
|
||||
|
||||
## 环境要求
|
||||
|
||||
### 必需软件
|
||||
- Go 1.23+
|
||||
- PostgreSQL 14+
|
||||
- Redis 6+
|
||||
- Docker & Docker Compose
|
||||
- Git
|
||||
|
||||
### 推荐工具
|
||||
- GoLand 或 VS Code
|
||||
- Postman 或 Insomnia
|
||||
- DBeaver (数据库管理)
|
||||
- Redis Desktop Manager
|
||||
|
||||
## 本地开发环境设置
|
||||
|
||||
### 1. 克隆项目
|
||||
```bash
|
||||
git clone <repository-url>
|
||||
cd photography-backend
|
||||
```
|
||||
|
||||
### 2. 安装依赖
|
||||
```bash
|
||||
go mod download
|
||||
```
|
||||
|
||||
### 3. 配置环境
|
||||
```bash
|
||||
# 复制配置文件
|
||||
cp configs/config.dev.yaml.example configs/config.dev.yaml
|
||||
|
||||
# 修改数据库配置
|
||||
vim configs/config.dev.yaml
|
||||
```
|
||||
|
||||
### 4. 启动服务
|
||||
```bash
|
||||
# 开发模式 (SQLite)
|
||||
make dev
|
||||
|
||||
# 完整模式 (PostgreSQL + Redis)
|
||||
make dev-full
|
||||
|
||||
# Mock 模式 (无数据库)
|
||||
make dev-simple
|
||||
```
|
||||
|
||||
### 5. 验证安装
|
||||
```bash
|
||||
# 检查服务状态
|
||||
curl http://localhost:8080/health
|
||||
|
||||
# 预期响应
|
||||
{
|
||||
"status": "healthy",
|
||||
"timestamp": "2024-01-01T00:00:00Z",
|
||||
"version": "1.0.0"
|
||||
}
|
||||
```
|
||||
|
||||
## 开发流程
|
||||
|
||||
### 1. 功能开发
|
||||
1. 创建功能分支: `git checkout -b feature/new-feature`
|
||||
2. 编写代码和测试
|
||||
3. 运行测试: `make test`
|
||||
4. 代码检查: `make lint`
|
||||
5. 提交代码: `git commit -m "feat: add new feature"`
|
||||
|
||||
### 2. 测试验证
|
||||
```bash
|
||||
# 运行单元测试
|
||||
make test-unit
|
||||
|
||||
# 运行集成测试
|
||||
make test-integration
|
||||
|
||||
# 运行所有测试
|
||||
make test
|
||||
|
||||
# 查看测试覆盖率
|
||||
make test-coverage
|
||||
```
|
||||
|
||||
### 3. 提交代码
|
||||
```bash
|
||||
# 格式化代码
|
||||
make fmt
|
||||
|
||||
# 代码检查
|
||||
make lint
|
||||
|
||||
# 构建项目
|
||||
make build
|
||||
|
||||
# 提交到远程
|
||||
git push origin feature/new-feature
|
||||
```
|
||||
```
|
||||
|
||||
## 📋 变更日志
|
||||
|
||||
### 版本管理
|
||||
```markdown
|
||||
# changelog/CHANGELOG.md - 版本变更记录
|
||||
|
||||
# 变更日志
|
||||
|
||||
本项目遵循 [语义化版本](https://semver.org/lang/zh-CN/) 规范。
|
||||
|
||||
## [未发布]
|
||||
|
||||
### 新增
|
||||
- 新功能开发中...
|
||||
|
||||
### 修改
|
||||
- 改进功能...
|
||||
|
||||
### 修复
|
||||
- 修复问题...
|
||||
|
||||
### 删除
|
||||
- 移除废弃功能...
|
||||
|
||||
## [1.2.0] - 2024-01-15
|
||||
|
||||
### 新增
|
||||
- 添加照片批量上传功能
|
||||
- 支持照片 EXIF 信息提取
|
||||
- 新增照片搜索 API
|
||||
- 添加用户头像上传功能
|
||||
- 支持照片分类管理
|
||||
- 新增 API 限流中间件
|
||||
|
||||
### 修改
|
||||
- 优化照片列表查询性能
|
||||
- 改进错误处理机制
|
||||
- 更新 API 响应格式
|
||||
- 优化数据库查询索引
|
||||
- 改进日志记录格式
|
||||
|
||||
### 修复
|
||||
- 修复文件上传大小限制问题
|
||||
- 解决并发操作的数据竞争问题
|
||||
- 修复 JWT Token 过期处理
|
||||
- 解决照片删除时的缓存清理问题
|
||||
- 修复分页查询的边界条件
|
||||
|
||||
### 安全
|
||||
- 加强文件上传安全验证
|
||||
- 改进密码强度要求
|
||||
- 添加请求频率限制
|
||||
- 优化 SQL 注入防护
|
||||
|
||||
## [1.1.0] - 2024-01-01
|
||||
|
||||
### 新增
|
||||
- 用户注册和登录功能
|
||||
- JWT 认证机制
|
||||
- 用户权限管理
|
||||
- 照片上传和管理
|
||||
- RESTful API 接口
|
||||
- 数据库迁移系统
|
||||
|
||||
### 修改
|
||||
- 重构代码架构
|
||||
- 优化性能表现
|
||||
- 改进错误处理
|
||||
|
||||
## [1.0.0] - 2023-12-01
|
||||
|
||||
### 新增
|
||||
- 项目初始版本
|
||||
- 基础框架搭建
|
||||
- 核心功能实现
|
||||
```
|
||||
|
||||
## 🛠️ 文档维护
|
||||
|
||||
### 文档编写规范
|
||||
1. **Markdown 格式**: 使用标准 Markdown 语法
|
||||
2. **结构清晰**: 合理使用标题层级
|
||||
3. **代码示例**: 提供完整可运行的示例
|
||||
4. **版本同步**: 文档与代码版本保持同步
|
||||
5. **定期更新**: 定期检查和更新文档内容
|
||||
|
||||
### 文档生成工具
|
||||
```bash
|
||||
# 生成 API 文档
|
||||
make docs-api
|
||||
|
||||
# 生成 Swagger UI
|
||||
make docs-swagger
|
||||
|
||||
# 生成完整文档站点
|
||||
make docs-build
|
||||
|
||||
# 启动文档服务器
|
||||
make docs-serve
|
||||
```
|
||||
|
||||
### 文档发布流程
|
||||
1. **编写文档**: 按照模板编写文档
|
||||
2. **本地预览**: 使用工具预览效果
|
||||
3. **代码审查**: 提交 PR 进行审查
|
||||
4. **自动部署**: 合并后自动发布到文档站点
|
||||
|
||||
## 💡 最佳实践
|
||||
|
||||
### API 文档编写
|
||||
1. **完整性**: 包含所有接口的详细说明
|
||||
2. **示例丰富**: 提供请求和响应示例
|
||||
3. **错误说明**: 详细说明各种错误情况
|
||||
4. **版本控制**: 明确 API 版本兼容性
|
||||
5. **交互式**: 支持在线测试功能
|
||||
|
||||
### 架构文档维护
|
||||
1. **及时更新**: 架构变更后立即更新文档
|
||||
2. **图文并茂**: 使用图表说明复杂概念
|
||||
3. **决策记录**: 记录重要的架构决策过程
|
||||
4. **影响分析**: 说明变更对系统的影响
|
||||
5. **迁移指南**: 提供版本迁移的详细步骤
|
||||
|
||||
### 开发文档规范
|
||||
1. **步骤详细**: 提供详细的操作步骤
|
||||
2. **环境说明**: 明确开发环境要求
|
||||
3. **故障排查**: 包含常见问题的解决方案
|
||||
4. **最佳实践**: 分享开发经验和技巧
|
||||
5. **持续改进**: 根据反馈不断完善文档
|
||||
|
||||
本模块确保项目文档的完整性和准确性，为开发者和用户提供清晰的指导。
|
||||
Reference in New Issue
Block a user