xlxumu/docs/architecture/后端架构文档.md

后端架构文档

版本历史

版本	日期	作者	变更说明
1.0	2024-01-20	后端团队	初始版本

1. 后端架构概述

1.1 架构目标

• 高性能：支持高并发请求处理
• 高可用：99.9%以上的服务可用性
• 可扩展：支持水平和垂直扩展
• 易维护：模块化设计，便于开发和维护
• 安全性：完善的安全防护机制

1.2 技术栈

• 运行环境：Node.js 18.x LTS
• Web框架：Express.js 4.x
• 开发语言：TypeScript 5.x
• ORM框架：Sequelize 6.x (MySQL) + Mongoose 7.x (MongoDB)
• 缓存：Redis 6.x
• 消息队列：Redis Pub/Sub + Bull Queue
• 文件存储：阿里云OSS
• 监控：Winston + Prometheus

2. 系统架构设计

2.1 分层架构

┌─────────────────────────────────────────────────────────────┐
│                    Controller Layer                         │
│                   (路由控制层)                               │
├─────────────────────────────────────────────────────────────┤
│                    Service Layer                            │
│                   (业务逻辑层)                               │
├─────────────────────────────────────────────────────────────┤
│                    Repository Layer                         │
│                   (数据访问层)                               │
├─────────────────────────────────────────────────────────────┤
│                    Model Layer                              │
│                   (数据模型层)                               │
└─────────────────────────────────────────────────────────────┘

2.2 微服务架构

┌─────────────────────────────────────────────────────────────┐
│                      API Gateway                           │
│                    (Nginx + Kong)                          │
└─────────────────────────────────────────────────────────────┘
                           │
┌─────────────┬─────────────┬─────────────┬─────────────────┐
│  用户服务   │  养殖服务   │  交易服务   │    通知服务     │
│ user-service│farm-service │trade-service│notify-service   │
│   :3001     │   :3002     │   :3003     │    :3004        │
└─────────────┴─────────────┴─────────────┴─────────────────┘

3. 核心服务设计

3.1 用户服务 (User Service)

端口: 3001 职责: 用户管理、认证授权、权限控制

核心模块:

• 认证模块: JWT Token生成和验证
• 用户管理: 用户注册、登录、信息管理
• 权限管理: RBAC权限控制
• 微信集成: 微信小程序授权登录

API设计:

// 用户注册
POST /api/v1/users/register
// 用户登录
POST /api/v1/users/login
// 获取用户信息
GET /api/v1/users/profile
// 更新用户信息
PUT /api/v1/users/profile

3.2 养殖服务 (Farm Service)

端口: 3002 职责: 养殖场管理、动物管理、饲料管理

核心模块:

• 养殖场管理: 养殖场信息、环境监控
• 动物管理: 动物档案、健康记录、生长数据
• 饲料管理: 饲料库存、投喂记录、营养分析
• 数据统计: 养殖数据分析和报表

API设计:

// 养殖场管理
GET /api/v1/farms
POST /api/v1/farms
PUT /api/v1/farms/:id
DELETE /api/v1/farms/:id

// 动物管理
GET /api/v1/animals
POST /api/v1/animals
PUT /api/v1/animals/:id

3.3 交易服务 (Trade Service)

端口: 3003 职责: 订单管理、支付管理、物流管理

核心模块:

• 订单管理: 订单创建、状态跟踪、订单历史
• 支付管理: 微信支付、支付宝支付集成
• 物流管理: 物流信息、配送跟踪
• 财务管理: 收支记录、财务报表

API设计:

// 订单管理
GET /api/v1/orders
POST /api/v1/orders
PUT /api/v1/orders/:id/status

// 支付管理
POST /api/v1/payments/wechat
POST /api/v1/payments/alipay
GET /api/v1/payments/:id/status

3.4 通知服务 (Notify Service)

端口: 3004 职责: 消息推送、邮件发送、短信通知

核心模块:

• 推送管理: 小程序消息推送
• 邮件服务: 邮件模板、批量发送
• 短信服务: 验证码、通知短信
• 消息队列: 异步消息处理

4. 数据库设计

4.1 MySQL数据库

用途: 核心业务数据存储

数据库分片策略:

• 用户库: 按用户ID分片
• 业务库: 按业务类型分库
• 日志库: 按时间分表

主要数据表:

-- 用户表
CREATE TABLE users (
    id BIGINT PRIMARY KEY AUTO_INCREMENT,
    username VARCHAR(50) UNIQUE NOT NULL,
    password VARCHAR(255) NOT NULL,
    phone VARCHAR(20),
    email VARCHAR(100),
    status TINYINT DEFAULT 1,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
);

-- 养殖场表
CREATE TABLE farms (
    id BIGINT PRIMARY KEY AUTO_INCREMENT,
    user_id BIGINT NOT NULL,
    name VARCHAR(100) NOT NULL,
    address TEXT,
    area DECIMAL(10,2),
    type VARCHAR(50),
    status TINYINT DEFAULT 1,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    FOREIGN KEY (user_id) REFERENCES users(id)
);

4.2 Redis缓存

用途: 缓存热点数据、会话存储、分布式锁

缓存策略:

• 用户会话: session:{token} (TTL: 7天)
• 用户信息: user:{id} (TTL: 1小时)
• 热点数据: hot:{type}:{id} (TTL: 30分钟)
• 分布式锁: lock:{resource} (TTL: 30秒)

4.3 MongoDB文档库

用途: 日志数据、统计数据、非结构化数据

集合设计:

// 操作日志
{
  _id: ObjectId,
  userId: Number,
  action: String,
  resource: String,
  details: Object,
  ip: String,
  userAgent: String,
  timestamp: Date
}

// 统计数据
{
  _id: ObjectId,
  type: String, // daily, weekly, monthly
  date: Date,
  metrics: {
    userCount: Number,
    orderCount: Number,
    revenue: Number
  }
}

5. 中间件设计

5.1 认证中间件

export const authMiddleware = async (req: Request, res: Response, next: NextFunction) => {
  try {
    const token = req.headers.authorization?.replace('Bearer ', '');
    if (!token) {
      return res.status(401).json({ error: 'Token required' });
    }
    
    const decoded = jwt.verify(token, process.env.JWT_SECRET!);
    req.user = decoded;
    next();
  } catch (error) {
    return res.status(401).json({ error: 'Invalid token' });
  }
};

5.2 权限中间件

export const permissionMiddleware = (permission: string) => {
  return async (req: Request, res: Response, next: NextFunction) => {
    const userPermissions = await getUserPermissions(req.user.id);
    if (!userPermissions.includes(permission)) {
      return res.status(403).json({ error: 'Permission denied' });
    }
    next();
  };
};

5.3 限流中间件

export const rateLimitMiddleware = rateLimit({
  windowMs: 15 * 60 * 1000, // 15分钟
  max: 100, // 最多100次请求
  message: 'Too many requests',
  standardHeaders: true,
  legacyHeaders: false,
});

6. API设计规范

6.1 RESTful API规范

• URL设计: 使用名词复数形式，如 /api/v1/users
• HTTP方法: GET(查询)、POST(创建)、PUT(更新)、DELETE(删除)
• 状态码: 200(成功)、201(创建)、400(参数错误)、401(未授权)、403(禁止)、404(未找到)、500(服务器错误)

6.2 响应格式

// 成功响应
{
  "success": true,
  "data": {},
  "message": "操作成功"
}

// 错误响应
{
  "success": false,
  "error": {
    "code": "USER_NOT_FOUND",
    "message": "用户不存在"
  }
}

// 分页响应
{
  "success": true,
  "data": {
    "items": [],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 100,
      "pages": 5
    }
  }
}

6.3 参数验证

import Joi from 'joi';

const userSchema = Joi.object({
  username: Joi.string().min(3).max(30).required(),
  password: Joi.string().min(6).required(),
  email: Joi.string().email().optional(),
  phone: Joi.string().pattern(/^1[3-9]\d{9}$/).optional()
});

export const validateUser = (req: Request, res: Response, next: NextFunction) => {
  const { error } = userSchema.validate(req.body);
  if (error) {
    return res.status(400).json({
      success: false,
      error: {
        code: 'VALIDATION_ERROR',
        message: error.details[0].message
      }
    });
  }
  next();
};

7. 错误处理机制

7.1 全局错误处理

export const errorHandler = (err: Error, req: Request, res: Response, next: NextFunction) => {
  logger.error('Unhandled error:', err);
  
  if (err instanceof ValidationError) {
    return res.status(400).json({
      success: false,
      error: {
        code: 'VALIDATION_ERROR',
        message: err.message
      }
    });
  }
  
  if (err instanceof AuthenticationError) {
    return res.status(401).json({
      success: false,
      error: {
        code: 'AUTHENTICATION_ERROR',
        message: '认证失败'
      }
    });
  }
  
  // 默认服务器错误
  res.status(500).json({
    success: false,
    error: {
      code: 'INTERNAL_SERVER_ERROR',
      message: '服务器内部错误'
    }
  });
};

7.2 自定义错误类

export class BusinessError extends Error {
  constructor(
    public code: string,
    public message: string,
    public statusCode: number = 400
  ) {
    super(message);
    this.name = 'BusinessError';
  }
}

export class ValidationError extends BusinessError {
  constructor(message: string) {
    super('VALIDATION_ERROR', message, 400);
  }
}

export class AuthenticationError extends BusinessError {
  constructor(message: string = '认证失败') {
    super('AUTHENTICATION_ERROR', message, 401);
  }
}

8. 日志系统

8.1 日志配置

import winston from 'winston';

const logger = winston.createLogger({
  level: process.env.LOG_LEVEL || 'info',
  format: winston.format.combine(
    winston.format.timestamp(),
    winston.format.errors({ stack: true }),
    winston.format.json()
  ),
  transports: [
    new winston.transports.File({ filename: 'logs/error.log', level: 'error' }),
    new winston.transports.File({ filename: 'logs/combined.log' }),
    new winston.transports.Console({
      format: winston.format.simple()
    })
  ]
});

8.2 日志中间件

export const loggerMiddleware = (req: Request, res: Response, next: NextFunction) => {
  const start = Date.now();
  
  res.on('finish', () => {
    const duration = Date.now() - start;
    logger.info('HTTP Request', {
      method: req.method,
      url: req.url,
      statusCode: res.statusCode,
      duration,
      userAgent: req.get('User-Agent'),
      ip: req.ip
    });
  });
  
  next();
};

9. 缓存策略

9.1 多级缓存

• L1缓存: 内存缓存 (Node.js进程内)
• L2缓存: Redis缓存 (分布式缓存)
• L3缓存: 数据库查询缓存

9.2 缓存更新策略

• Cache Aside: 应用程序管理缓存
• Write Through: 写入时同步更新缓存
• Write Behind: 异步更新缓存

9.3 缓存实现

class CacheService {
  private redis: Redis;
  private localCache: Map<string, any>;
  
  async get(key: string): Promise<any> {
    // 先查本地缓存
    if (this.localCache.has(key)) {
      return this.localCache.get(key);
    }
    
    // 再查Redis缓存
    const value = await this.redis.get(key);
    if (value) {
      this.localCache.set(key, JSON.parse(value));
      return JSON.parse(value);
    }
    
    return null;
  }
  
  async set(key: string, value: any, ttl: number = 3600): Promise<void> {
    // 更新本地缓存
    this.localCache.set(key, value);
    
    // 更新Redis缓存
    await this.redis.setex(key, ttl, JSON.stringify(value));
  }
}

10. 性能优化

10.1 数据库优化

• 连接池: 使用连接池管理数据库连接
• 索引优化: 合理创建索引提升查询性能
• 查询优化: 避免N+1查询，使用JOIN优化
• 分页优化: 使用游标分页替代OFFSET

10.2 API优化

• 响应压缩: 启用Gzip压缩
• 静态资源: CDN加速静态资源
• 异步处理: 耗时操作异步处理
• 批量操作: 支持批量API操作

10.3 内存优化

• 内存监控: 监控内存使用情况
• 垃圾回收: 优化垃圾回收策略
• 内存泄漏: 定期检查内存泄漏

11. 安全设计

11.1 输入验证

• 参数校验: 严格校验所有输入参数
• SQL注入: 使用ORM防止SQL注入
• XSS防护: 输出内容转义处理

11.2 认证安全

• 密码加密: bcrypt加密存储密码
• Token安全: JWT Token + 刷新机制
• 会话管理: 安全的会话管理

11.3 传输安全

• HTTPS: 强制使用HTTPS传输
• CORS: 配置跨域资源共享
• CSP: 内容安全策略

12. 监控与运维

12.1 健康检查

app.get('/health', (req, res) => {
  res.json({
    status: 'ok',
    timestamp: new Date().toISOString(),
    uptime: process.uptime(),
    memory: process.memoryUsage(),
    version: process.env.npm_package_version
  });
});

12.2 性能监控

• 响应时间: 监控API响应时间
• 错误率: 监控错误发生率
• 吞吐量: 监控请求处理量
• 资源使用: 监控CPU、内存使用

12.3 告警机制

• 阈值告警: 基于指标阈值告警
• 异常告警: 异常情况实时告警
• 趋势告警: 基于趋势变化告警

13. 部署架构

13.1 容器化部署

FROM node:18-alpine

WORKDIR /app

COPY package*.json ./
RUN npm ci --only=production

COPY . .

EXPOSE 3000

CMD ["npm", "start"]

13.2 Kubernetes部署

apiVersion: apps/v1
kind: Deployment
metadata:
  name: backend-service
spec:
  replicas: 3
  selector:
    matchLabels:
      app: backend-service
  template:
    metadata:
      labels:
        app: backend-service
    spec:
      containers:
      - name: backend
        image: backend-service:latest
        ports:
        - containerPort: 3000
        env:
        - name: NODE_ENV
          value: "production"

14. 扩展性设计

14.1 水平扩展

• 无状态设计: 服务无状态，便于扩展
• 负载均衡: 支持多实例负载均衡
• 数据分片: 支持数据库分片扩展

14.2 垂直扩展

• 资源配置: 支持动态调整资源配置
• 性能调优: 支持性能参数调优
• 容量规划: 基于业务增长规划容量