mini-shop-server

构建微信小程序(商城)后端
🤜基于 Flask 框架🤛

Mini Shop Server 是一个基于现代化 Flask 框架构建的微信小程序商城后端系统，专为中小型企业和开发者提供完整、可靠、易扩展的电商后端解决方案。

线上 API 文档

本项目的开发环境是 Mac OS，生产环境是 Linux Ubuntu 16.04
感谢慕课网的七月老师，本项目初期是基于他的课程思路

✨ 亮点

基于原生的 Flask 构建 RESTful API
更灵活的 API文档生成方式(可带 Token)
AOP(面向切面编程)设计，实现 参数校验层 & 异常统一处理层
现代化包管理：使用 uv 替代 pipenv，提供更快的依赖安装和解析
Ubuntu 16.04+ 上 Nginx + Gunicorn + uv 部署

项目架构体系

🔩 内置

用户管理：提供用户的相关配置
权限组(角色)管理：接口权限分配和菜单权限分配
菜单管理：实现后端配置菜单动态路由，支持多级菜单
字典管理：维护系统中经常使用的字典数据，如：性别，状态
参数管理：系统动态配置常用参数，如：分页数，前端主题色等
通知管理：系统通知&公告信息的发布维护
日志管理：操作日志和登录日志
接口文档：根据业务代码自动生成相关的api接口文档(Swagger风格)
错误码：前后端开发的错误码的约定
文件管理和上传：文件夹和文件的管理
文章管理

开发工具

Python 3.12（虚拟环境：uv）
PostgreSQL
PyCharm 或 VSCode（开发工具）
Navicat（数据库可视化管理工具）

开发环境搭建

PostgreSQL安装、运行，数据库的导入
Python 3.12

PostgreSQL的安装和数据导入

一、安装

$ sudo apt-get install postgresql postgresql-contrib

安装完成后，为 postgres 用户设置密码：

$ sudo -u postgres psql -c "ALTER USER postgres WITH PASSWORD 'postgres123';"

请务必记住密码!
务必记住密码！
记住密码！

查看是否安装成功

``$ sudo netstat -tap | grep postgres

#### 二、运行


$ sudo -u postgres psql              # 以 postgres 用户进入 psql 命令行
$ psql -h localhost -U postgres -W   # 指定主机和用户连接(输入密码)
-U 表示连接的用户名，  -h 表示主机地址<br>
 上面命令执行之后，会提示输入密码(Enter password)
三、导入
使用项目根目录下的 zerd_pg.sql（PostgreSQL 版本的种子数据）
> PostgreSQL 的每条执行以「分号」结尾
$ createdb -h localhost -U postgres zerd                 # 建立数据库(zerd)
$ psql -h localhost -U postgres -d zerd -f zerd_pg.sql   # 导入「mini-shop-server」目录下的 sql 文件
> Tips: 其他数据库操作<br>
// 1. 获取存在的所有表
postgres=# \dt
// 2. 导入成功，可以直接查询(user表)
postgres=# select * from "user";
// 3. 删除数据库(zerd库)
postgres=# drop database zerd;
// 4. 导出数据库
$ pg_dump -h localhost -U postgres zerd > zerd_pg.sql
### Python3.12版本的安装
查询本地的python3的版本
$ python3 --version如果不是python3.12的版本，则如下操作
$ sudo apt-get update 
$ sudo apt-get install software-properties-common
$ sudo add-apt-repository ppa:deadsnakes/ppa
$ sudo apt-get install python3.12
### uv的安装
安装 uv 包管理工具 (推荐方式)bash
$ curl -LsSf https://astral.sh/uv/install.sh | sh
或者使用 pip 安装bash
$ pip install uv
> Tips: uv 常用操作命令bash
$ uv --version                    # 查看版本
$ uv python list                  # 查看可用Python版本
$ uv venv --python 3.12           # 创建指定Python版本的虚拟环境
$ uv sync                         # 安装依赖
$ uv add flask                    # 添加依赖
$ uv add flask==2.0.3             # 添加指定版本依赖
$ uv remove flask                 # 删除依赖
$ uv run python server.py         # 在虚拟环境中运行命令
$ source .venv/bin/activate       # 激活虚拟环境
$ source .venv/Scripts/activate   # windows 上激活虚拟环境
### 本地启动bash
$ git clone https://github.com/Allen7D/mini-shop-server.git
$ git clone --depth=1 -b master --single-branch [email protected]:Allen7D/mini-shop-server.git  # 浅克隆(只克隆指定分支，且只下载最近的提交历史)
$ cd mini-shop-server 
$ uv venv --python 3.12           # 创建指定 Python 3.12 版本的虚拟环境
$ uv sync                         # 创建虚拟环境并安装所有依赖
$ uv run python server.py run     # 启动方式1:默认5000端口
$ uv run python server.py run -p 8080                 # 启动方式2:改为8080端口
$ uv run python server.py run -h 0.0.0.0 -p 8080     # 启动方式3:以本地IP地址访问
或者激活虚拟环境后运行
$ source .venv/bin/activate       # 激活虚拟环境
$ source .venv/Scripts/activate   # windows 上激活虚拟环境
$ python server.py run            # 在虚拟环境中直接运行
### 开发环境生成临时管理员信息bash
$ uv run python fake.py
### IDE 配置
PyCharm 配置 uv 环境
获取 uv 虚拟环境的 Python 解释器路径bash$ uv run which python
或者
$ uv python find
2. PyCharm 中配置 Python 解释器
   - 打开 File > Settings > Project > Python Interpreter
   - 点击 Add Interpreter > Existing environment  
   - 选择 .venv/bin/python（Linux/Mac）或 .venv/Scripts/python.exe（Windows）
配置运行配置
   - Run > Edit Configurations
   - Script path: server.py
   - Parameters: run -h 0.0.0.0 -p 8080
VSCode 配置 uv 环境
安装 Python 扩展
打开命令面板 (Ctrl+Shift+P)

选择 Python: Select Interpreter

选择项目中的 .venv/bin/python 解释器

VSCode 会自动识别虚拟环境

!image.png
!image.png
创建 .vscode/settings.json 配置文件：json
{
    "python.defaultInterpreterPath": "./.venv/bin/python",
    "python.terminal.activateEnvironment": true
}
## Docker 一键启动（推荐）
无需手动安装 Python/PostgreSQL，只需安装 Docker Desktop，即可一条命令拉起「应用 + 数据库」两个容器。
> Dockerfile + .dockerignore + docker-compose.yml 已内置；db 容器首次初始化会自动执行 zerd_pg.sql 建表并灌入种子数据。

快速启动bash
1. 下载代码并进入项目目录
$ git clone https://github.com/Allen7D/mini-shop-server.git
$ cd mini-shop-server
2. 构建并一键启动（首次会拉取镜像+构建，稍慢）
$ docker compose up -d --build
启动后执行 docker compose ps，看到 app 与 db 两个容器均为 Up 即启动成功。
✅ 成功标志：浏览器打开 http://localhost:8080/apidocs/#/ ，能看到 Swagger 接口文档页面，即表示一切正常。
后台管理员账号
> 说明：种子数据（zerd_pg.sql）主要提供业务数据，其中的旧账号密码哈希已失效，无法直接登录。如需可登录的测试账号，请用 fake.py 一键生成。bash
docker compose exec app uv run python fake.py
生成账号（用户名 / 密码）：
| 用户名 | 密码   | 角色       |
| ------ | ------ | ---------- |
| super  | 123456 | 超级管理员 |
| admin  | 123456 | 普通管理员 |
| user   | 123456 | 普通用户   |
> 注意：用户名、邮箱、微信 openid 均有唯一约束，fake.py 重复运行会报「唯一约束」错误，生成一次即可。

常用命令bash
$ docker compose logs -f app   # 实时查看应用日志
$ docker compose down          # 停止
$ docker compose down -v       # 停止并删除数据库数据卷（重置数据）
### 连接数据库（TablePlus / Navicat 等可视化工具）
app 容器访问数据库走的是 Docker 内部网络——连接串 postgresql+pg8000://postgres:postgres123@db:5432/zerd 里的 db 是服务名（由 Compose 网络内置 DNS 解析成容器内网 IP），因此不需要对外暴露端口，应用也能正常连库。

但我们的数据库可视化工具（TablePlus、Navicat 等）跑在宿主机上，默认连不到容器内的数据库——因为 db 的 5432 端口没有映射到宿主机。两者的区别：
app 容器 ── db:5432 ──▶ db 容器（容器内部网络，天然互通）
宿主机(可视化工具) ──✗──▶ db 容器（宿主端口未映射，连不上）
要让可视化工具连接，需在 docker-compose.yml 中为 db 服务取消端口映射注释：yaml
  db:
    # ...
    ports:
      - "5432:5432"        # 左侧「宿主端口」:右侧「容器端口」
然后重启生效：bash
$ docker compose up -d
之后用以下信息连接：
| 参数     | 值                              |
| -------- | ------------------------------- |
| Host     | localhost（或 127.0.0.1）    |
| Port     | 5432                          |
| User     | postgres                      |
| Password | postgres123                   |
| Database | zerd                          |

> 注意：默认注释掉端口映射，正是为了规避「宿主机 5432 已被其它 PostgreSQL 占用」的冲突。若你的宿主机 5432 已被占用，把左侧端口改成其它值即可，例如 "15432:5432"，可视化工具里 Port 填 15432。

> 不想暴露端口时，也可直接在容器内查询，无需映射端口：
> docker compose exec db psql -U postgres -d zerd

静态资源示例：http://localhost:8080/static/images/[email protected]
微信小程序相关配置（APP_ID/APP_SECRET 等）可在 docker-compose.yml 中取消注释并填写。

目录结构
<details>
<summary>展开查看</summary>
<pre><code>
.
├── app
│   ├── __init__.py
│   ├── api
│   │   ├── v1          # v1的API接口
│   │   │   ├── __init__.py
│   │   │   ├── address.py  # 用户地址
│   │   │   ├── banner.py   # 推广横幅
│   │   │   ├── category.py # 分类
│   │   │   ├── client.py
│   │   │   ├── order.py    # 订单
│   │   │   ├── pay.py      # 支付
│   │   │   ├── product.py  # 产品
│   │   │   ├── theme.py    # 主题
│   │   │   ├── token.py    # 令牌
│   │   │   └── user.py     # 用户
│   │   └── v2 # v2的API接口
│   │       ├── __init__.py
│   │       └── file.py     # 文件上传
│   ├── api_docs        # 对应的 API文档
│   ├── config # 配置文件
│   │   ├── secure.py
│   │   ├── setting.py
│   │   └── wx.py
│   ├── libs # 自己的库
│   │   ├── enums.py
│   │   ├── error.py
│   │   ├── error_code.py
│   │   ├── httper.py
│   │   ├── limiter.py
│   │   ├── redprint.py
│   │   ├── scope.py
│   │   ├── swagger_filed.py
│   │   ├── token_auth.py
│   │   └── utils.py
│   ├── models          # Model 层
│   ├── service # Service 层
│   │   ├── __init__.py
│   │   ├── app_token.py
│   │   ├── order.py
│   │   ├── pay.py
│   │   ├── token.py
│   │   └── wx_token.py
│   ├── validators      # 参数校验层
│   │   ├── __init__.py
│   │   ├── base.py
│   │   ├── forms.py
│   │   └── params.py
│   ├── web             # 网页文件
│   │   ├── __init__.py
│   │   └── auth.py
│   └── app.py
├── fake.py             # 生成临时用户
├── server.py           # 启动程序(项目入口)
├── config.ini
├── pyproject.toml      # uv 项目配置和依赖文件
├── uv.lock             # uv 锁定文件 (自动生成)
├── Pipfile             # 旧的 pipenv 配置文件 (可删除)
├── code.md             # 错误码(用于前后端开发)
├── README.md           # 项目说明文档
├── zerd_pg.sql
└── LICENSE
</code></pre>
</details>
业务逻辑分成
DAO层(数据访问层)，全称为data access object
<br>属于一种比较底层，比较基础的操作，对于数据库的操作，具体到对于某个表的增删改查。
<br>DAO一定是和数据库的某一张表一一对应的，其中封装了增删改查基本操作，建议DAO只做原子操作，增删改查。
Service层(服务层)
<br>是对一个或多个DAO进行的再次封装，封装成一个服务，因此不只是一个原子操作，需要事务控制。
Controller层(业务层)
<br>管理用户的操作，用户界面传过的请求，调用对应的服务（service），完成用户请求的处理.
自动生成 api 接口文档
Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful风格的 Web 服务。
本项目使用 Flasgger库自动生成 Swagger 风格(Demo)的API文档。
Swagger Editor 在网页端直接编辑 API 文档
查阅 API文档(本项目)
> 启动服务(DEBUG 模式下)<br>
在浏览器端输入：http://localhost:8080/apidocs/#/
使用 Token
基于 HTTPBasicAuth 来传递token<br>
所以, Postman 中 Authorization 设置使用 Basic Auth;<br>
Flassger 中 securityDefinitions 设置使用 basicAuth (详见config/setting.py)
服务器部署
本项目选择在 Ubuntu 16.04+ 上，用 Nginx + Gunicorn + uv 部署<sup>[[3]](#ref_3)</sup>，其中 Gunicorn 取代 uWsgi。
> Flask 与 uWsgi 结合有许多难以处理的 bug
服务器安装 uvbash
curl -LsSf https://astral.sh/uv/install.sh | sh
### 部署步骤bash
1. 克隆项目
git clone https://github.com/Allen7D/mini-shop-server.git
cd mini-shop-server
2. 使用 uv 安装依赖
uv sync
3. 运行服务
uv run gunicorn -w 4 -b 127.0.0.1:8080 server:app # 在8080端口开启 gunicorn
fuser -k 8080/tcp # 关闭占用8080端口的服务
## 本地&线上同步推进
业务场景
本地与线上使用不同的密钥、数据库等敏感配置，这些内容不应以明文提交到代码仓库。
解决
统一使用 .env(已 gitignore) 存放敏感配置，启动时由 python-dotenv 加载，app/config/secure.py 从环境变量读取。
使用步骤
复制模板并填入真实值(Windows 使用 copy)：bash   cp .env.example .env
   2. 编辑 .env，填写 SECRET_KEY、SQLALCHEMY_DATABASE_URI、APP_ID/APP_SECRET 等
安装依赖并启动：bash   uv sync
   uv run python server.py run
   > .env 已在 .gitignore 中，不会被提交；系统环境变量优先于 .env，生产环境可直接注入环境变量。
上传&下载
上传<sup>[[2]](#ref_2)</sup>
具体查看 app/api/v2/file.py 的 upload_file 视图函数
下载
1. 「静态资源文件」下载
默认下载路径前缀 http://0.0.0.0:8080/static/
访问 app/static/images 目录下的资源
http://0.0.0.0:8080/static/images/[email protected]
访问 app/static/files 目录下的资源
http://0.0.0.0:8080/static/files/Python面向对象编程指南.epub
###对第三方库的装饰器的扩展
具体查看 app/lib/redprint.py 的 doc 函数
不改动第三方库 Flasgger的 swag_from(装饰器函数)的源码，对其进行了功能的扩展
Nginx 部署
$ nginx -s stop # 停止 nginx
$ nginx -s reload # 重启 nginx
### Nginx 配置
建立 文件A 快捷方式 文件B : ln –s 源文件A 目标文件B <br>
以 /etc/nginx/sites-available/server 为源文件，以 /etc/nginx/sites-enabled/server 为目标文件，使得2个文件同步。<br>
ln -s /etc/nginx/sites-available/server /etc/nginx/sites-enabled/server
/etc/nginx/sites-available/server 配置如下:bash
server {
    listen 443 default;
    server_name www.ivinetrue.com ivinetrue.com; 
    ssl on;
    root html;
    index index.html index.htm;
    access_log /var/log/nginx/access.log;
    error_log /var/log/nginx/error.log;
    ssl_certificate cert/ivinetrue.pem;
    ssl_certificate_key cert/ivinetrue.key;
    ssl_session_timeout 10m;
    ssl_ciphers ECDHE-RSA-AES128-GCM-SHA256:ECDHE:ECDH:AES:HIGH:!NULL:!aNULL:!MD5:!ADH:!RC4;
    ssl_protocols TLSv1 TLSv1.1 TLSv1.2;
    ssl_prefer_server_ciphers on;
    location / {
        include proxy_params;
        proxy_pass http://unix:/home/workspace/mini-shop-server/server.sock;
        # proxy_pass http://127.0.0.1:8080; # 弃用
        proxy_redirect off;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_headers_hash_max_size 51200;
        proxy_headers_hash_bucket_size 6400;
    }
    location /static/ {
        alias /home/workspace/mini-shop-server/app/static/; # 静态资源文件路径
    }
}
server {
      listen  80;
      server_name www.ivinetrue.com ivinetrue.com;
      rewrite ^(.*)$  https://$host$1 permanent; # https 代理
}
### Nginx 其他配置
Nginx 的公共配置(例如: gzip)需要修改 /etc/nginx/nginx.conf
supervisor 配置
路径 /etc/supervisor/conf.d/server.conf
配置文件bash
[program:server]
environment=PATH='/root/.local/share/virtualenvs/server-4o3oDD8t/bin/python'
command = /root/.local/share/virtualenvs/server-4o3oDD8t/bin/gunicorn -w 4 -b unix:/home/workspace/morning-star/server/server.sock server:app
directory = /home/workspace/morning-star/server
user = root
#日志输出
stderr_logfile=/tmp/blog_stderr.log
stdout_logfile=/tmp/blog_stdout.log

运行supervisorctl restart server`

使用

第一步:

第二步:

第三步:

后续

三端分离

1.客户端: mini-shop-wx

微信小程序链接。

2.服务端: mini-shop-server

基于 Flask框架构建 RESTful API。

点击查阅 API文档(Swagger风格)

3.CMS: mini-shop-cms

基于 Vue.js框架和Element-UI组件库链接

Python3 学习路线(亲测)

路线: 1 -> 2 -> 3 -> 4

参考

【1】PyCharm配置使用Flask-Script启动以及开启Debug模式

【2】Flask 上传文件

【3】Flask + Gunicorn + Nginx 部署

【4】centos7 下通过nginx+uwsgi部署django应用

【5】Nginx的https配置记录以及http强制跳转到https的方法梳理

【6】Nginx配置HTTPS

【7】PostgreSQL 数据库备份与恢复

【8】Automatically enable HTTPS on your website with EFF's Certbot.

【9】ubuntu16.04 64bit 升级 python3.5 python3.6

【10】Lin-CMS：优秀的 Flask & Vue 结合的前后端分离的 CMS 解决方案

【11】基于Linux环境搭建Nginx+uWSGI+Python框

Allen7D/mini-shop-server: 基于 Flask 框架开发的微信小程序后端项目，用于构建小程序商城后台 （电商相关；rbac权限管理；附带自动生成Swagger 风格的API 文档；可作「Python 项目毕设」）

mini-shop-server

构建微信小程序(商城)后端 🤜基于 Flask 框架🤛

✨ 亮点

🔩 内置

目录

开发工具

开发环境搭建

PostgreSQL的安装和数据导入

一、安装

三、导入

或者激活虚拟环境后运行

PyCharm 配置 uv 环境

或者

VSCode 配置 uv 环境

快速启动

1. 下载代码并进入项目目录

2. 构建并一键启动（首次会拉取镜像+构建，稍慢）

后台管理员账号

常用命令

目录结构

业务逻辑分成

自动生成 api 接口文档

使用 Token

服务器部署

服务器安装 uv

1. 克隆项目

2. 使用 uv 安装依赖

3. 运行服务

业务场景

解决

使用步骤

上传&下载

上传<sup>[[2]](#ref_2)</sup>

下载

1. 「静态资源文件」下载

Nginx 部署

supervisor 配置

使用

第一步:

第二步:

第三步:

后续

三端分离

1.客户端: mini-shop-wx

2.服务端: mini-shop-server

3.CMS: mini-shop-cms

Python3 学习路线(亲测)

参考

Star History

Reading Mode

Related Stories

Say Please (if only as a reminder)

Code Review Is Not an Authority Boundary

I Got a Signed Job Offer Letter for a Job that Never Existed

OpenAI agents and RubyGems: what the May attack report found

I Gave ChatGPT My Full Codebase. The Results Scared Me — But Not for the Reason You Think.

Related Stories

Allen7D/mini-shop-server: 基于 Flask 框架开发的微信小程序后端项目，用于构建小程序商城后台（电商相关；rbac权限管理；附带自动生成Swagger 风格的API 文档；可作「Python 项目毕设」）

构建微信小程序(商城)后端
🤜基于 Flask 框架🤛

`快速启动`

`常用命令`

`服务器安装 uv`

`Nginx 部署`