325 lines
7.0 KiB
Markdown
325 lines
7.0 KiB
Markdown
# 录音应用架构文档
|
|
|
|
## 架构概述
|
|
|
|
本项目采用现代化的全栈架构，参考了多个优秀开源项目的设计模式：
|
|
|
|
- **Next.js 14** - 全栈 React 框架
|
|
- **领域驱动设计 (DDD)** - 业务逻辑分层
|
|
- **Clean Architecture** - 清晰的依赖关系
|
|
- **错误处理模式** - 参考 Stripe 的错误处理
|
|
- **API 设计** - 参考 GitHub 的 RESTful API 设计
|
|
|
|
## 项目结构
|
|
|
|
```
|
|
record-app/
|
|
├── src/
|
|
│ ├── app/ # Next.js App Router
|
|
│ │ ├── api/ # API 路由层
|
|
│ │ │ ├── auth/ # 认证 API
|
|
│ │ │ ├── recordings/ # 录音管理 API
|
|
│ │ │ └── user/ # 用户管理 API
|
|
│ │ ├── dashboard/ # 主面板页面
|
|
│ │ ├── login/ # 登录页面
|
|
│ │ ├── register/ # 注册页面
|
|
│ │ ├── profile/ # 个人资料页面
|
|
│ │ ├── settings/ # 设置页面
|
|
│ │ └── layout.tsx # 根布局
|
|
│ ├── components/ # React 组件层
|
|
│ │ ├── ui/ # 基础 UI 组件
|
|
│ │ │ ├── button.tsx # 按钮组件
|
|
│ │ │ └── ...
|
|
│ │ ├── features/ # 功能组件
|
|
│ │ │ ├── audio-recorder/
|
|
│ │ │ ├── audio-player/
|
|
│ │ │ └── user-menu/
|
|
│ │ └── layout/ # 布局组件
|
|
│ ├── lib/ # 核心库层
|
|
│ │ ├── config/ # 配置管理
|
|
│ │ ├── database.ts # 数据库连接
|
|
│ │ ├── auth.ts # 认证配置
|
|
│ │ ├── services/ # 业务服务层
|
|
│ │ │ ├── user.service.ts
|
|
│ │ │ └── recording.service.ts
|
|
│ │ ├── errors/ # 错误处理
|
|
│ │ │ └── app-error.ts
|
|
│ │ ├── middleware/ # 中间件
|
|
│ │ │ └── error-handler.ts
|
|
│ │ ├── utils/ # 工具函数
|
|
│ │ │ ├── api-response.ts
|
|
│ │ │ └── cn.ts
|
|
│ │ └── types/ # 类型定义
|
|
│ └── styles/ # 样式文件
|
|
├── prisma/ # 数据库层
|
|
│ ├── schema.prisma # 数据库模式
|
|
│ └── migrations/ # 数据库迁移
|
|
├── public/ # 静态资源
|
|
│ └── recordings/ # 录音文件存储
|
|
└── docs/ # 文档
|
|
```
|
|
|
|
## 架构层次
|
|
|
|
### 1. 表现层 (Presentation Layer)
|
|
|
|
- **位置**: `src/app/` 和 `src/components/`
|
|
- **职责**: 用户界面和 API 路由
|
|
- **特点**:
|
|
- 使用 Next.js App Router
|
|
- 组件化设计
|
|
- 响应式布局
|
|
|
|
### 2. 应用层 (Application Layer)
|
|
|
|
- **位置**: `src/lib/services/`
|
|
- **职责**: 业务逻辑和用例
|
|
- **特点**:
|
|
- 领域服务模式
|
|
- 事务管理
|
|
- 业务规则验证
|
|
|
|
### 3. 领域层 (Domain Layer)
|
|
|
|
- **位置**: `src/lib/` 核心业务逻辑
|
|
- **职责**: 核心业务规则
|
|
- **特点**:
|
|
- 领域驱动设计
|
|
- 实体和值对象
|
|
- 领域事件
|
|
|
|
### 4. 基础设施层 (Infrastructure Layer)
|
|
|
|
- **位置**: `prisma/` 和数据库相关
|
|
- **职责**: 数据持久化和外部服务
|
|
- **特点**:
|
|
- 数据库抽象
|
|
- 文件存储
|
|
- 外部 API 集成
|
|
|
|
## 设计模式
|
|
|
|
### 1. 服务层模式 (Service Layer Pattern)
|
|
|
|
```typescript
|
|
// 用户服务
|
|
export class UserService {
|
|
static async createUser(data: CreateUserData): Promise<User>;
|
|
static async getUserById(id: string): Promise<UserProfile | null>;
|
|
static async updateUser(
|
|
id: string,
|
|
data: UpdateUserData
|
|
): Promise<UserProfile>;
|
|
}
|
|
```
|
|
|
|
### 2. 错误处理模式 (Error Handling Pattern)
|
|
|
|
```typescript
|
|
// 自定义错误类
|
|
export class AppError extends Error {
|
|
public readonly statusCode: number
|
|
public readonly isOperational: boolean
|
|
public readonly code?: string
|
|
}
|
|
|
|
// 具体错误类型
|
|
export class ValidationError extends AppError
|
|
export class AuthenticationError extends AppError
|
|
export class NotFoundError extends AppError
|
|
```
|
|
|
|
### 3. 响应处理模式 (Response Pattern)
|
|
|
|
```typescript
|
|
// 统一 API 响应格式
|
|
export interface ApiResponse<T = any> {
|
|
success: boolean;
|
|
data?: T;
|
|
error?: {
|
|
message: string;
|
|
code?: string;
|
|
details?: any;
|
|
};
|
|
meta?: {
|
|
timestamp: string;
|
|
requestId?: string;
|
|
};
|
|
}
|
|
```
|
|
|
|
### 4. 中间件模式 (Middleware Pattern)
|
|
|
|
```typescript
|
|
// 错误处理中间件
|
|
export class ErrorHandler {
|
|
static async handle<T>(
|
|
handler: (req: NextRequest) => Promise<NextResponse<T>>,
|
|
req: NextRequest
|
|
): Promise<NextResponse>;
|
|
}
|
|
```
|
|
|
|
## 数据流
|
|
|
|
### 1. API 请求流程
|
|
|
|
```
|
|
客户端请求 → API 路由 → 中间件 → 服务层 → 数据库 → 响应
|
|
```
|
|
|
|
### 2. 错误处理流程
|
|
|
|
```
|
|
错误发生 → 错误中间件 → 错误分类 → 统一响应格式 → 客户端
|
|
```
|
|
|
|
### 3. 认证流程
|
|
|
|
```
|
|
用户登录 → NextAuth → JWT Token → 会话管理 → 权限验证
|
|
```
|
|
|
|
## 配置管理
|
|
|
|
### 1. 环境配置
|
|
|
|
```typescript
|
|
export const config = {
|
|
app: { name: "录音应用", version: "1.0.0" },
|
|
database: { url: process.env.DATABASE_URL! },
|
|
auth: { secret: process.env.NEXTAUTH_SECRET! },
|
|
upload: { maxFileSize: 50 * 1024 * 1024 },
|
|
features: { audioVisualization: true },
|
|
};
|
|
```
|
|
|
|
### 2. 特性开关
|
|
|
|
- 音频可视化
|
|
- 录音暂停功能
|
|
- 文件下载
|
|
- 用户设置
|
|
|
|
## 安全考虑
|
|
|
|
### 1. 认证安全
|
|
|
|
- JWT Token 管理
|
|
- 密码哈希 (bcrypt)
|
|
- 会话管理
|
|
|
|
### 2. 数据安全
|
|
|
|
- 输入验证
|
|
- SQL 注入防护 (Prisma)
|
|
- 文件上传限制
|
|
|
|
### 3. API 安全
|
|
|
|
- 速率限制
|
|
- CORS 配置
|
|
- 错误信息脱敏
|
|
|
|
## 性能优化
|
|
|
|
### 1. 数据库优化
|
|
|
|
- 连接池管理
|
|
- 查询优化
|
|
- 索引策略
|
|
|
|
### 2. 前端优化
|
|
|
|
- 组件懒加载
|
|
- 图片优化
|
|
- 缓存策略
|
|
|
|
### 3. API 优化
|
|
|
|
- 响应缓存
|
|
- 分页查询
|
|
- 数据压缩
|
|
|
|
## 测试策略
|
|
|
|
### 1. 单元测试
|
|
|
|
- 服务层测试
|
|
- 工具函数测试
|
|
- 组件测试
|
|
|
|
### 2. 集成测试
|
|
|
|
- API 路由测试
|
|
- 数据库集成测试
|
|
- 认证流程测试
|
|
|
|
### 3. 端到端测试
|
|
|
|
- 用户流程测试
|
|
- 录音功能测试
|
|
- 错误处理测试
|
|
|
|
## 部署架构
|
|
|
|
### 1. 开发环境
|
|
|
|
- 本地数据库 (SQLite)
|
|
- 热重载开发
|
|
- 调试工具
|
|
|
|
### 2. 生产环境
|
|
|
|
- 云数据库
|
|
- CDN 加速
|
|
- 监控告警
|
|
|
|
## 扩展性考虑
|
|
|
|
### 1. 水平扩展
|
|
|
|
- 无状态设计
|
|
- 数据库读写分离
|
|
- 负载均衡
|
|
|
|
### 2. 功能扩展
|
|
|
|
- 插件化架构
|
|
- 模块化设计
|
|
- API 版本管理
|
|
|
|
### 3. 技术栈扩展
|
|
|
|
- 微服务拆分
|
|
- 消息队列
|
|
- 缓存层
|
|
|
|
## 最佳实践
|
|
|
|
### 1. 代码组织
|
|
|
|
- 单一职责原则
|
|
- 依赖注入
|
|
- 接口隔离
|
|
|
|
### 2. 错误处理
|
|
|
|
- 统一错误格式
|
|
- 错误日志记录
|
|
- 用户友好提示
|
|
|
|
### 3. 性能监控
|
|
|
|
- 性能指标收集
|
|
- 错误追踪
|
|
- 用户行为分析
|
|
|
|
## 参考项目
|
|
|
|
- **Vercel/Next.js** - 现代化全栈框架
|
|
- **Discord** - 大规模应用架构
|
|
- **GitHub** - API 设计和错误处理
|
|
- **Stripe** - 支付系统架构
|
|
- **Shopify** - 电商平台架构
|