章节1：项目架构与设计

学习目标

完成本章学习后，你将能够：

掌握需求分析与产品原型梳理的方法论
理解全栈项目的系统架构设计原则（Vue3 + Django + MySQL + Redis）
独立完成数据库表结构设计（ER 图与关系建模）
制定接口规范并约定前后端协作标准
完成项目初始化，配置 Git / ESLint / Pylint 等工程规范

1.1 需求分析与产品原型梳理

1.1.1 需求分析的核心流程

定义：需求分析是软件工程的第一阶段，目标是明确系统"要做什么"，将模糊的业务诉求转化为可落地的功能清单。

业务流程梳理 → 角色与用例识别 → 功能模块划分 → 优先级排序 → 原型确认

需求分类：

类型	说明	示例
功能需求	系统直接提供的功能	用户注册、商品搜索、下单支付
非功能需求	性能、安全、可用性等	并发 1000、响应 < 2s、HTTPS
业务需求	来自业务方的目标	转化率提升 20%
用户需求	终端用户的使用场景	快速找到想要的商品

1.1.2 原型设计工具与产出

常用工具：Axure RP、Figma、墨刀、Sketch

产出物：

├── 线框图（Wireframe）—— 低保真，确定布局与信息结构
├── 高保真原型（High-fidelity）—— 实际 UI 样式、交互动效
└── PRD 文档（产品需求文档）—— 文字描述每个页面/功能的规则

1.2 系统架构与技术选型

1.2.1 整体架构分层

定义：系统架构是软件的骨架结构，决定了各模块的职责划分与通信方式。

采用 前后端分离 的 B/S 架构，分为四层：

┌─────────────────────────────────────────────┐
│      前端层（Vue3） - 浏览器 / H5           │
│  Vue Router + Pinia + Axios + Element Plus   │
├─────────────────────────────────────────────┤
│        API 网关层（Nginx）                   │
│    反向代理 / 负载均衡 / 静态资源托管       │
├─────────────────────────────────────────────┤
│      后端层（Django + DRF）                  │
│   Django REST Framework + Celery + JWT Auth  │
├─────────────────────────────────────────────┤
│      数据层（MySQL + Redis）                 │
│   MySQL（关系数据） + Redis（缓存/会话）     │
└─────────────────────────────────────────────┘

1.2.2 技术选型对照表

技术栈	选择理由	替代方案
Vue3 + Composition API	响应式、TS 友好、生态成熟	React / Angular
Element Plus	Vue3 原生组件库，开箱即用	Ant Design Vue / Naive UI
Django + DRF	全栈框架、ORM 强大、Admin 内置	FastAPI / Flask
MySQL 8.0	事务支持成熟、生态完善	PostgreSQL
Redis	高性能缓存、支持分布式锁	Memcached
Celery	异步任务队列，处理短信/邮件/定时任务	Dramatiq / Hue
Docker	环境一致性与快速部署	Kubernetes（生产编排）

1.2.3 架构核心原则

"高内聚、低耦合" —— 每一层只关注自己的职责，通过 HTTP API 或消息队列进行通信。

python

# 后端视图层示例 —— 只做参数校验与响应返回
from rest_framework.views import APIView
from rest_framework.response import Response
from .services import OrderService

class OrderCreateView(APIView):
    def post(self, request):
        serializer = OrderCreateSerializer(data=request.data)
        serializer.is_valid(raise_exception=True)      # 校验
        order = OrderService.create_order(             # 业务逻辑下沉到 Service
            user=request.user, **serializer.validated_data
        )
        return Response(OrderSerializer(order).data)

1.3 数据库表结构设计

1.3.1 E-R 关系建模

定义：数据库设计是系统设计中最核心的环节之一，决定了数据的存储效率、查询性能与扩展性。

B2C 电商平台核心实体关系：

User（用户） 1 ── N  Order（订单）
User（用户） 1 ── N  CartItem（购物车项）
User（用户） 1 ── N  Address（收货地址）
Category（分类） 1 ── N  Product（商品）
Supplier（供应商） 1 ── N  Product（商品）
Product（商品） 1 ── N  OrderItem（订单明细）
Order（订单） 1 ── N  OrderItem（订单明细）
Order（订单） 1 ── 1  Payment（支付记录）

1.3.2 核心表结构设计

sql

-- ========== 用户表 ==========
CREATE TABLE `user` (
    `id`          BIGINT AUTO_INCREMENT PRIMARY KEY,
    `username`    VARCHAR(64)  NOT NULL UNIQUE,
    `password`    VARCHAR(256) NOT NULL COMMENT 'bcrypt 哈希',
    `phone`       VARCHAR(20)  NOT NULL UNIQUE,
    `email`       VARCHAR(128) NULL,
    `avatar`      VARCHAR(512) NULL,
    `is_active`   TINYINT(1)   NOT NULL DEFAULT 1,
    `is_staff`    TINYINT(1)   NOT NULL DEFAULT 0 COMMENT '后台管理员',
    `created_at`  DATETIME     NOT NULL DEFAULT CURRENT_TIMESTAMP,
    `updated_at`  DATETIME     NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    INDEX `idx_phone` (`phone`),
    INDEX `idx_username` (`username`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

-- ========== 商品分类表 ==========
CREATE TABLE `category` (
    `id`          BIGINT AUTO_INCREMENT PRIMARY KEY,
    `name`        VARCHAR(64)  NOT NULL,
    `parent_id`   BIGINT       NULL COMMENT '父分类ID，支持多级分类',
    `level`       TINYINT      NOT NULL DEFAULT 1,
    `sort_order`  INT          NOT NULL DEFAULT 0,
    `created_at`  DATETIME     NOT NULL DEFAULT CURRENT_TIMESTAMP,
    FOREIGN KEY (`parent_id`) REFERENCES `category`(`id`) ON DELETE SET NULL
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

-- ========== 商品表 ==========
CREATE TABLE `product` (
    `id`            BIGINT AUTO_INCREMENT PRIMARY KEY,
    `category_id`   BIGINT       NOT NULL,
    `name`          VARCHAR(256) NOT NULL,
    `description`   TEXT,
    `price`         DECIMAL(10,2) NOT NULL COMMENT '原价',
    `discount_price`DECIMAL(10,2) NULL COMMENT '折扣价',
    `stock`         INT          NOT NULL DEFAULT 0,
    `sales_count`   INT          NOT NULL DEFAULT 0,
    `status`        TINYINT      NOT NULL DEFAULT 1 COMMENT '1上架 0下架',
    `images`        JSON         NULL COMMENT '商品图片URL数组',
    `created_at`    DATETIME     NOT NULL DEFAULT CURRENT_TIMESTAMP,
    `updated_at`    DATETIME     NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    FOREIGN KEY (`category_id`) REFERENCES `category`(`id`),
    INDEX `idx_category` (`category_id`),
    INDEX `idx_status` (`status`),
    FULLTEXT INDEX `ft_name_desc` (`name`, `description`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

1.3.3 Django ORM 模型定义

python

# backend/apps/product/models.py
from django.db import models

class Category(models.Model):
    name = models.CharField(max_length=64, verbose_name="分类名称")
    parent = models.ForeignKey(
        'self', on_delete=models.SET_NULL, null=True, blank=True,
        related_name='children', verbose_name="父分类"
    )
    level = models.PositiveSmallIntegerField(default=1, verbose_name="层级")
    sort_order = models.IntegerField(default=0, verbose_name="排序")
    created_at = models.DateTimeField(auto_now_add=True)

    class Meta:
        db_table = 'category'
        verbose_name = '商品分类'
        ordering = ['sort_order', 'id']

    def __str__(self):
        return self.name


class Product(models.Model):
    category = models.ForeignKey(
        Category, on_delete=models.CASCADE, related_name='products',
        verbose_name="所属分类"
    )
    name = models.CharField(max_length=256, verbose_name="商品名称")
    description = models.TextField(blank=True, verbose_name="商品描述")
    price = models.DecimalField(max_digits=10, decimal_places=2, verbose_name="原价")
    discount_price = models.DecimalField(
        max_digits=10, decimal_places=2, null=True, blank=True, verbose_name="折扣价"
    )
    stock = models.IntegerField(default=0, verbose_name="库存")
    sales_count = models.IntegerField(default=0, verbose_name="销量")
    is_active = models.BooleanField(default=True, verbose_name="上架状态")
    images = models.JSONField(default=list, verbose_name="商品图片")
    created_at = models.DateTimeField(auto_now_add=True)
    updated_at = models.DateTimeField(auto_now=True)

    class Meta:
        db_table = 'product'
        verbose_name = '商品'
        indexes = [
            models.Index(fields=['category']),
            models.Index(fields=['is_active']),
        ]

    def __str__(self):
        return self.name

1.4 接口规范与前后端约定

1.4.1 RESTful API 设计规范

定义：REST（Representational State Transfer）是一种资源导向的 API 设计风格，使用 HTTP 动词表达操作。

方法	操作	路径示例	说明
GET	查询（列表）	`/api/v1/products/`	分页获取商品列表
GET	查询（详情）	`/api/v1/products/{id}/`	获取单个商品详情
POST	创建	`/api/v1/orders/`	创建订单
PUT	全量更新	`/api/v1/users/{id}/`	更新用户资料
PATCH	部分更新	`/api/v1/cart/{id}/`	修改购物车数量
DELETE	删除	`/api/v1/cart/{id}/`	删除购物车项

1.4.2 统一响应格式

json

// 成功响应
{
    "code": 200,
    "message": "success",
    "data": {
        "id": 1,
        "username": "alice",
        "email": "alice@example.com"
    }
}

// 分页响应
{
    "code": 200,
    "message": "success",
    "data": {
        "results": [ ... ],
        "total": 100,
        "page": 1,
        "page_size": 10
    }
}

// 错误响应
{
    "code": 4001,
    "message": "参数校验失败",
    "errors": {
        "username": ["该用户名已被注册"],
        "email": ["邮箱格式不正确"]
    }
}

1.4.3 前后端协作流程

前端（Vue3）                    后端（Django）
    │                               │
    │  ① 根据接口文档 Mock 数据      │
    │─── ② 并行开发 ──────────────→ │
    │  ③ Axios 请求拦截器 + Token   │
    │←── ④ 联调对接 ───────────────│
    │  ⑤ 修复差异，回归测试        │
    │                               │

推荐工具：

Swagger / OpenAPI：自动生成接口文档，前后端统一视图
Apifox / Postman：接口调试与 Mock 服务
DRF Spectacular：Django REST Framework 的 OpenAPI 生成器

python

# 使用 drf-spectacular 自动生成接口文档
from drf_spectacular.views import SpectacularAPIView, SpectacularSwaggerView

urlpatterns = [
    path('api/schema/', SpectacularAPIView.as_view(), name='schema'),
    path('api/docs/', SpectacularSwaggerView.as_view(url_name='schema'), name='swagger-ui'),
]

1.5 项目初始化与代码规范

1.5.1 项目目录结构

bash

ecommerce-platform/
├── frontend/                    # Vue3 前端项目
│   ├── public/
│   ├── src/
│   │   ├── api/                 # Axios 接口封装
│   │   ├── assets/              # 静态资源
│   │   ├── components/          # 公共组件
│   │   ├── layouts/             # 布局组件
│   │   ├── router/              # 路由配置
│   │   ├── stores/              # Pinia 状态管理
│   │   ├── views/               # 页面组件
│   │   ├── utils/               # 工具函数
│   │   ├── App.vue
│   │   └── main.ts
│   ├── .eslintrc.cjs
│   ├── vite.config.ts
│   └── package.json
├── backend/                     # Django 后端项目
│   ├── apps/
│   │   ├── user/                # 用户模块
│   │   ├── product/             # 商品模块
│   │   ├── order/               # 订单模块
│   │   ├── payment/             # 支付模块
│   │   └── admin/               # 后台管理模块
│   ├── config/
│   │   ├── settings/            # 分环境配置
│   │   │   ├── base.py
│   │   │   ├── dev.py
│   │   │   └── prod.py
│   │   ├── urls.py
│   │   └── wsgi.py
│   ├── scripts/                 # 管理脚本
│   ├── manage.py
│   ├── requirements.txt
│   ├── .pylintrc
│   └── Dockerfile
├── docs/                        # 项目文档
├── docker-compose.yml           # 容器编排
└── README.md

1.5.2 Git 工作流

定义：Git 工作流是团队协作的代码管理规范，约定分支命名、合并流程与发布策略。

推荐：Git Feature Flow

bash

# 主分支
main          # 生产环境代码，只允许从 release/hotfix 合并
develop       # 开发主分支

# 辅助分支
feature/*     # 功能开发分支  feature/user-auth
release/*     # 发布分支      release/v1.0.0
hotfix/*      # 紧急修复      hotfix/payment-bug

# 协作流程
git checkout -b feature/user-login develop
# ... 开发、提交 ...
git checkout develop
git merge --no-ff feature/user-login
git branch -d feature/user-login

1.5.3 ESLint 配置（前端）

javascript

// frontend/.eslintrc.cjs
module.exports = {
  root: true,
  env: { browser: true, es2021: true, node: true },
  extends: [
    'eslint:recommended',
    'plugin:vue/vue3-recommended',
    '@vue/typescript/recommended',
    'plugin:prettier/recommended',
  ],
  rules: {
    'vue/multi-word-component-names': 'off',
    '@typescript-eslint/no-explicit-any': 'warn',
    'no-console': process.env.NODE_ENV === 'production' ? 'warn' : 'off',
    'no-debugger': process.env.NODE_ENV === 'production' ? 'warn' : 'off',
    'max-len': ['warn', { code: 120, ignoreComments: true }],
  },
};

1.5.4 Pylint 配置（后端）

ini

# backend/.pylintrc
[MASTER]
load-plugins = pylint_django

[MESSAGES CONTROL]
disable =
    C0114,    # missing-module-docstring
    C0115,    # missing-class-docstring
    C0116,    # missing-function-docstring
    R0903,    # too-few-public-methods
    W0614,    # unused-wildcard-import

[FORMAT]
max-line-length = 120

[DESIGN]
max-args = 8
max-locals = 20

1.5.5 项目初始化命令速查

bash

# ===== 前端初始化 =====
pnpm create vite frontend --template vue-ts
cd frontend
pnpm add vue-router@4 pinia axios element-plus element-plus/icons-vue
pnpm add -D eslint prettier eslint-plugin-vue @typescript-eslint/parser

# ===== 后端初始化 =====
cd backend
python -m venv venv
pip install django djangorestframework django-cors-headers
pip install mysqlclient redis celery drf-spectacular
django-admin startproject config .
python manage.py startapp apps.user
python manage.py startapp apps.product

小结

知识回顾

需求分析：从业务诉求到功能清单，产出 PRD + 原型，是项目成功的基石
系统架构：Vue3 + Django + MySQL + Redis 的分层架构，前后端分离，职责清晰
数据库设计：E-R 关系建模 → 表结构设计 → ORM 映射，三层递进
接口规范：RESTful 风格 + 统一响应格式 + Swagger 文档自动化
项目规范：Git Feature Flow + ESLint + Pylint，保证团队协作质量

练习与思考

需求分析练习：以"校园二手书交易平台"为题，写出至少 8 个功能需求，并画出功能模块图
数据库设计：基于上题的需求，设计 book（图书）和 transaction（交易记录）两张表的 DDL
接口设计：设计商品列表接口的请求参数（分页、排序、筛选）和响应格式
项目初始化：按照本课的目录规范，在本地初始化一个完整的电商项目骨架
思考题：为什么选择 JWT 而不是 Session 做用户认证？JWT 的优缺点是什么？

章节1：项目架构与设计 ​

学习目标 ​

1.1 需求分析与产品原型梳理 ​

1.1.1 需求分析的核心流程 ​

1.1.2 原型设计工具与产出 ​

1.2 系统架构与技术选型 ​

1.2.1 整体架构分层 ​

1.2.2 技术选型对照表 ​

1.2.3 架构核心原则 ​

1.3 数据库表结构设计 ​

1.3.1 E-R 关系建模 ​

1.3.2 核心表结构设计 ​

1.3.3 Django ORM 模型定义 ​

1.4 接口规范与前后端约定 ​

1.4.1 RESTful API 设计规范 ​

1.4.2 统一响应格式 ​

1.4.3 前后端协作流程 ​

1.5 项目初始化与代码规范 ​

1.5.1 项目目录结构 ​

1.5.2 Git 工作流 ​

1.5.3 ESLint 配置（前端） ​

1.5.4 Pylint 配置（后端） ​

1.5.5 项目初始化命令速查 ​

小结 ​

知识回顾 ​

练习与思考 ​

章节1：项目架构与设计

学习目标

1.1 需求分析与产品原型梳理

1.1.1 需求分析的核心流程

1.1.2 原型设计工具与产出

1.2 系统架构与技术选型

1.2.1 整体架构分层

1.2.2 技术选型对照表

1.2.3 架构核心原则

1.3 数据库表结构设计

1.3.1 E-R 关系建模

1.3.2 核心表结构设计

1.3.3 Django ORM 模型定义

1.4 接口规范与前后端约定

1.4.1 RESTful API 设计规范

1.4.2 统一响应格式

1.4.3 前后端协作流程

1.5 项目初始化与代码规范

1.5.1 项目目录结构

1.5.2 Git 工作流

1.5.3 ESLint 配置（前端）

1.5.4 Pylint 配置（后端）

1.5.5 项目初始化命令速查

小结

知识回顾

练习与思考