基于Flask与微信小程序的手机银行系统实战解析

1. 手机银行系统的整体技术选型：为什么是Flask加微信小程序

前阵子手上接了一套基于微信小程序的手机银行业务系统，后端用 Python 的 Flask 框架从零搭建。做完之后最想聊的不是某个 API 怎么写，而是整套系统的技术选型和边界划分。毕竟"手机银行"四个字听起来很重，但落到具体功能上，无非就是登录、绑卡、余额查询、转账、流水明细这几件事，而这几件事恰恰是前后端配合最典型、最容易踩坑的场景。

这套系统服务端只承担业务逻辑和数据存储，小程序端负责展示和交互。选 Flask 的核心原因是它足够轻，不需要像 Django 那样自带一整套全家桶，路由、蓝图、SQLAlchemy 一接，一个中小型金融类业务项目就很清晰了。加上 Flask 的生态非常成熟，登录鉴权有 Flask-JWT-Extended，迁移有 Flask-Migrate，ORM 有 Flask-SQLAlchemy，这些配套一组合，写起来非常顺畅。

那为什么不选 FastAPI 或者 Django？我在实际对比之后发现，FastAPI 的异步特性对这个系统帮助不大，因为交易类逻辑大量依赖数据库事务和行锁，本质上还是同步 IO 为主。Django 虽然自带 admin 后台很好用，但项目体量不大时，Django 的迁移成本、配置复杂度都略高。Flask 更像一个"插件拼装"的方案，你需要什么就装什么，项目结构完全由自己控制，这对理解系统底层非常友好。

1.1 系统角色与核心业务链路

在动工之前，我先把业务流程从头到尾走了一遍。手机银行系统里至少有两个角色：普通用户和管理员。用户端在小程序里完成注册登录、绑定银行卡、查看余额、转账、查流水；管理端可以查看用户列表、账户状态、交易明细、处理异常流水。

用户核心链路是：打开小程序 → 授权手机号登录 → 绑定一张银行卡 → 查看账户余额与流水 → 发起转账 → 转账结果落库并生成流水记录。这条链路决定了后端接口的边界：登录注册、账户信息、转账交易、流水查询，前两类属于基础能力，后两类涉及资金安全，是整个系统设计的重点。

1.2 前后端边界：小程序只负责表达，不负责判断

"手机银行"这类系统，前后端职责必须分清楚。小程序端我只做三件事：收集用户输入、调用后端接口、渲染返回结果。所有金额计算、身份验证、状态校验全部放在后端，哪怕是前端算出来的余额，后端也要重新校验一遍。

举个最简单的例子：用户在转账页面输入金额时，前端会先做一次"金额大于0、不超过余额"的提示，但真正扣钱发生在后端，后端必须重新校验余额，而且要用数据库事务保证"扣款"和"加款"同时成功。这一点如果不从一开始就明确，后期很容易写出"前端校验得很开心、后端一测就出漏洞"的局面。所以整套系统的架构是前后端完全分离，接口通过 JSON 交换数据，小程序端不直接操作数据库。

2. 后端项目骨架搭建：Flask目录结构、依赖与配置管理

2.1 按业务模块拆分的目录设计

做 Flask 项目最容易犯的错就是把所有路由堆在 app.py 里，前期爽，后期乱。这套系统我用了蓝图加业务模块目录，骨架大致长这样：

bank_system/ ├── app/ │ ├── __init__.py # 应用工厂 │ ├── extensions.py # db、jwt 等扩展实例 │ ├── config/ │ │ ├── __init__.py │ │ ├── default.py # 默认配置 │ │ ├── development.py # 本地开发配置 │ │ └── production.py # 生产配置 │ ├── models/ │ │ ├── __init__.py │ │ ├── user.py # 用户模型 │ │ ├── account.py # 账户模型 │ │ └── transaction.py # 流水模型 │ ├── api/ │ │ ├── __init__.py │ │ ├── auth.py # 登录/注册 │ │ ├── account.py # 账户/卡管理 │ │ └── transfer.py # 转账/流水查询 │ └── utils/ │ ├── __init__.py │ ├── response.py # 统一返回格式 │ └── decorators.py # 自定义装饰器 ├── migrations/ # Flask-Migrate 迁移文件 ├── wsgi.py # 启动入口 └── requirements.txt

应用工厂模式是 Flask 项目里我很推荐的写法，create_app()里完成配置加载、扩展注册、蓝图注册，好处是测试的时候可以很方便地创建不同配置的实例，而不是动全局变量。

2.2 依赖清单：版本锁定比想象中重要

很多初学者装依赖习惯直接pip install flask flask-sqlalchemy，然后全用最新版，结果换台机器一跑就崩。这套系统我把 requirements.txt 锁到了具体版本：

Flask==2.3.3 Flask-SQLAlchemy==3.1.1 Flask-Migrate==4.0.7 Flask-JWT-Extended==4.5.3 PyMySQL==1.1.0 cryptography==41.0.7 requests==2.31.0 gunicorn==21.2.0

版本锁定的原因很现实：Flask 2.x 和 3.x 在部分扩展兼容性上有差别，某个小版本更新可能影响原有接口行为。本地开发时我建议先建虚拟环境，再安装依赖，避免和系统 Python 环境里的包互相污染。我第一次用 PyMySQL 连 MySQL 时顺手装了个最新版，结果和 Flask-SQLAlchemy 默认的 MySQLdb 驱动冲突，报错查了半天，最后锁版本才稳定下来。

2.3 配置分离：敏感信息不进代码库

配置管理是这套系统里最容易被忽视的部分。我把配置按环境拆成多个类：默认配置放公共项，开发配置开调试模式，生产配置单独读环境变量。

class Config: SECRET_KEY = os.environ.get('SECRET_KEY', 'dev-secret-key') SQLALCHEMY_TRACK_MODIFICATIONS = False JSON_AS_ASCII = False class DevelopmentConfig(Config): DEBUG = True SQLALCHEMY_DATABASE_URI = 'mysql+pymysql://root:password@localhost/bank_dev' class ProductionConfig(Config): DEBUG = False SQLALCHEMY_DATABASE_URI = os.environ.get('DATABASE_URL')

这里有个关键点：数据库密码、JWT 密钥、微信小程序的 AppSecret 绝对不能写死在代码里。生产环境的密钥通过环境变量注入，.env文件只存在于本地，并且要加进.gitignore。不然代码一旦推到仓库，等价于把数据库和用户数据的门钥匙公开了，这在金融类项目里是绝对的红线。

3. 核心业务API的实现逻辑：登录、余额、转账与流水查询

3.1 微信小程序登录：从 code 到 openid 再到自定义 token

小程序端的登录和传统账号密码登录完全不一样。用户在 button 上点了允许授权后，前端拿到一个临时code，把它传给后端，后端拿这个 code 去微信服务端换openid和session_key。

@auth_bp.route('/wxlogin', methods=['POST']) def wx_login(): code = request.json.get('code') appid = current_app.config['WX_APPID'] secret = current_app.config['WX_SECRET'] url = 'https://api.weixin.qq.com/sns/jscode2session' resp = requests.get(url, params={ 'appid': appid, 'secret': secret, 'js_code': code, 'grant_type': 'authorization_code' }).json() if 'openid' not in resp: return jsonify(code=1, msg='登录失败：%s' % resp.get('errmsg')) openid = resp['openid'] session_key = resp['session_key'] # 查询或创建用户 user = User.query.filter_by(openid=openid).first() if not user: user = User(openid=openid, nickname='微信用户') db.session.add(user) db.session.commit() # 生成自定义 token token = create_access_token(identity=str(user.id)) return jsonify(code=0, data={'token': token, 'user_id': user.id})

为什么不直接拿 openid 当 token？因为 openid 是用户的稳定身份标识，一旦泄露，别人可以伪装成这个用户的所有请求。自定义 token 是短期有效的，过期之后重新走登录流程，这才是安全设计的基本手段。session_key这里也要妥善保存，后面解密手机号会用到，但绝不能返回给前端。

3.2 手机号获取：getPhoneNumber 回调的解密流程

小程序端button open-type="getPhoneNumber"拿到的是加密数据和 iv，需要后端调微信接口换手机号。现在推荐的做法是后端用access_token调微信的phonenumber.getPhoneNumber接口，传入前端给的code：

@auth_bp.route('/bind_phone', methods=['POST']) def bind_phone(): phone_code = request.json.get('phone_code') # 前端传的 code access_token = get_wx_access_token() url = 'https://api.weixin.qq.com/wxa/business/getuserphonenumber' resp = requests.post(url, params={'access_token': access_token}, json={'code': phone_code}).json() if resp.get('errcode') == 0: phone_info = resp['phone_info'] # phone_info.purePhoneNumber 就是手机号 user_id = get_jwt_identity() user = User.query.get(user_id) user.phone = phone_info['purePhoneNumber'] db.session.commit() return jsonify(code=0, data={'phone': user.phone}) return jsonify(code=1, msg='手机号获取失败')

这里最容易踩的坑是 access_token 的有效性。微信的 access_token 每天有获取次数限制，而且有效期只有两个小时，所以一定要在服务端做缓存，不能每次请求都去获取。我用了一个简单的内存缓存，存下 access_token 和获取时间，过期前两分钟重新获取，实测非常稳。

3.3 余额与流水查询：分页和状态筛选

余额查询和流水查询是用户天天用的接口，看似简单，但流水列表的查询要特别注意数据量。用户的每一笔转账、每一次绑定操作都会产生流水，时间久了数据量会很大，不能一次性全部返回。

@account_bp.route('/transactions', methods=['GET']) def get_transactions(): user_id = get_jwt_identity() page = request.args.get('page', 1, type=int) per_page = request.args.get('per_page', 20, type=int) t_type = request.args.get('type', None) # income/expense/all query = Transaction.query.filter_by(user_id=user_id) if t_type and t_type != 'all': query = query.filter_by(t_type=t_type) pagination = query.order_by(Transaction.create_time.desc()).paginate( page=page, per_page=per_page, error_out=False) return jsonify(code=0, data={ 'list': [t.to_dict() for t in pagination.items], 'total': pagination.total, 'page': page })

分页用的paginate是 Flask-SQLAlchemy 自带的，它会自动生成 count 查询，数据量大之后 count 会变慢，这是一个后话。但在系统初期，分页习惯的建立比优化重要得多，先有分页结构，再谈性能优化。

3.4 转账接口：事务、金额精度与并发控制

转账是整个系统里最关键的接口，接错一个细节就是资金事故。我用 SQLAlchemy 的with db.session.begin_nested()配合行锁来实现事务逻辑：

@transfer_bp.route('/transfer', methods=['POST']) def transfer(): user_id = get_jwt_identity() data = request.json target_card = data.get('target_card') amount = Decimal(str(data.get('amount'))).quantize(Decimal('0.01')) if amount <= 0: return jsonify(code=1, msg='金额必须大于0') # 锁定用户账户行，防止并发扣款 account = Account.query.filter_by(user_id=user_id).with_for_update().first() if not account or account.balance < amount: return jsonify(code=1, msg='余额不足') target_account = Account.query.filter_by(card_no=target_card).with_for_update().first() if not target_account: return jsonify(code=1, msg='收款账户不存在') account.balance -= amount target_account.balance += amount # 生成两笔流水：支出和收入 db.session.add(Transaction(user_id=user_id, t_type='expense', amount=amount, target_card=target_card, status='success', biz_no=generate_biz_no())) db.session.add(Transaction(user_id=target_account.user_id, t_type='income', amount=amount, source_card=account.card_no, status='success', biz_no=generate_biz_no())) db.session.commit() return jsonify(code=0, msg='转账成功')

用with_for_update()的意图很直接：并发场景下，两个请求同时读到余额是 1000，各自扣成 800 和 900，最后余额变成负数。行锁保证同一时间只有一个事务能改这行，扣完提交，另一个事务再读就是扣完后的值。金额用Decimal转字符串再做精确计算，是因为 Python 的 float 在二进制存储下会有精度误差，0.1+0.2 不等于 0.3，这在资金系统里完全不能接受。biz_no是业务单号，全局唯一，用来防重复提交。

4. 微信小程序端的关键实现：手机号获取、请求封装与导航适配

4.1 请求封装：统一处理 401 和错误码

小程序端的网络请求如果不做统一封装，每一个页面都写wx.request，代码会重复到怀疑人生。我做了一个request.js工具，所有请求走后端约定的返回结构，遇到 401 自动清理登录态并跳转登录页：

const BASE_URL = 'https://your-domain.com/api'; function request(path, method, data) { return new Promise((resolve, reject) => { wx.request({ url: BASE_URL + path, method: method, data: data, header: { 'Content-Type': 'application/json', 'Authorization': 'Bearer ' + wx.getStorageSync('token') }, success: (res) => { if (res.statusCode === 401) { wx.removeStorageSync('token'); wx.navigateTo({ url: '/pages/login/login' }); reject(new Error('登录已过期')); return; } if (res.data.code !== 0) { wx.showToast({ title: res.data.msg, icon: 'none' }); reject(new Error(res.data.msg)); return; } resolve(res.data.data); }, fail: reject }); }); } module.exports = { get: (path, data) => request(path, 'GET', data), post: (path, data) => request(path, 'POST', data) };

封装完之后，页面里调用接口变成request.get('/account/balance')，只管拿数据，错误处理全部在拦截层集中解决。而且 token 过期响应处理得非常果断：清掉本地 token，跳登录页，用户重新授权登录后就能继续操作，不会出现半个页面还在显示旧数据的诡异状态。

4.2 登录态管理：启动时检查，避免白屏

小程序一启动就要判断用户是否已登录，不然用户明明登录过，每次打开却都要求重新登录，体验很差。我在app.js的onLaunch里做了一次预处理：

onLaunch: function () { const token = wx.getStorageSync('token'); const userInfo = wx.getStorageSync('userInfo'); if (token && userInfo) { this.globalData.isLogin = true; this.globalData.userInfo = userInfo; } else { this.globalData.isLogin = false; } }

这里有个判断顺序的讲究：token存在不代表 token 仍然有效，真正的校验在首个需要登录态的接口返回 401 时再做。这种"乐观登录态"设计的好处是启动时不阻塞页面渲染，等到实际请求失败再引导用户重新登录，比每次启动都先调一次/auth/check要快得多。

4.3 登录页面的手机号授权细节

手机号授权的交互在小程序里有一个很大的坑：getPhoneNumber不是弹窗授权，而是必须用户主动点击按钮触发。而且从 2023 年起，新版本小程序需要用phoneNumber的code由后端调接口换手机号，不能再直接用encryptedData解密，不然会发现线上经常拿不到手机号。

我在登录页的button上加了open-type="getPhoneNumber"，回调里先走wx.login()获取登录 code，再把手机号 code 一起传给后端：

bindGetPhoneNumber(e) { if (!e.detail.code) { wx.showToast({ title: '需要授权手机号才能登录', icon: 'none' }); return; } wx.login({ success: (loginRes) => { request.post('/auth/wxlogin', { code: loginRes.code, phone_code: e.detail.code }).then((data) => { wx.setStorageSync('token', data.token); wx.setStorageSync('userInfo', data.userInfo); wx.switchTab({ url: '/pages/home/home' }); }); } }); }

用户拒绝授权时，e.detail.code是拿不到的，所以要给一个明确的提示，引导用户重新点击。这个交互在测试真机时一定要单独测，开发者工具模拟器的行为和真机有差异，我第一次就是在模拟器上一切正常，上了真机发现手机号一直拿不到，排查半天才意识到是接口调用方式已经改了。

4.4 顶部导航栏高度与安全区适配

微信小程序的顶部导航高度在不同机型上不同，尤其是有胶囊按钮的机型，如果写死navigationBarHeight: 44，在 iPhone 全面屏上就会出问题。我用wx.getWindowInfo()获取状态栏高度，再结合胶囊按钮的位置动态计算自定义导航高度：

const getNavBarHeight = () => { const winInfo = wx.getWindowInfo(); const menuInfo = wx.getMenuButtonBoundingClientRect(); const statusBarHeight = winInfo.statusBarHeight; const navBarHeight = (menuInfo.top - statusBarHeight) * 2 + menuInfo.height; return { statusBarHeight, navBarHeight }; };

这段逻辑的核心思路是：导航栏实际高度是胶囊按钮所在区域的高度，用状态栏到按钮顶部的距离乘以 2 再加上按钮自身高度就能算准。不同厂商的机型适配问题，在这个公式下基本都能避开。

5. 数据模型设计：从账户到流水的表结构及关系

5.1 核心表结构：用户、账户、银行卡、交易流水

手机银行系统的数据结构不算复杂，但关系要理清楚。用户表存基础信息，账户表存余额，银行卡表绑定具体卡号，流水表记录每一笔资金变动。我用 SQLAlchemy 模型定义并做了迁移，核心表结构大概如下：

balance_after这个字段很多人会忽略，但它非常关键：用户查流水时经常想知道"这笔交易之后余额是多少"，如果没有这个字段，前端就要拿之前的流水余额倒推，数据一旦有遗漏就对不上账了。在流水表里冗余一个balance_after，查询体验会好很多，代价只是多存一个字段。

5.2 流水幂等设计：防止重复提交

转账接口最怕的不是并发，而是用户手抖点了两下提交。两次请求进来，如果业务单号没有做唯一约束，就会生成两笔转账，资金直接翻倍。我的处理方式是每次转账前生成一个唯一的biz_no，并在数据库里加唯一索引。转账接口执行前，先查biz_no是否已经存在，存在就直接返回成功，不再重复扣款。

if Transaction.query.filter_by(biz_no=biz_no).first(): return jsonify(code=0, msg='重复请求，已处理')

这个字段约束在数据库层面兜底，就算应用层漏判，数据库唯一索引也会直接报错，最多表现为这条请求失败，而不会出现重复转账。幂等设计在支付类系统里是一等大事，手机银行系统虽然只是雏形，但这个习惯必须养成。

5.3 金额存储：数据库用 decimal，代码用 Decimal

前面提到金额计算用 Decimal，在数据库层面也要配套。MySQL 的DECIMAL(18,2)是定点数，可以精确表示两位小数，而FLOAT/DOUBLE是浮点数，同样存在精度问题。如果表结构里用了 float 存金额，查询统计时会出现 1.999999 这种诡异结果，排查起来非常麻烦。

在 SQLAlchemy 模型里，金额字段用Numeric(18, 2)，取出后在 Python 中就是 Decimal 对象。注意从 JSON 接口拿到金额时，要先用str()转字符串再Decimal()，避免把 float 的精度误差带进来。

5.4 流水查询的索引优化

流水表的数据增长速度是最快的，我给它建了两个关键索引：biz_no唯一索引用于幂等判断，(user_id, create_time)联合索引用于流水分页查询。没有这个联合索引，按用户查流水时 MySQL 会做全表扫描，用户量大了之后接口会越来越慢。初期建表时把索引设计好，比后期数据量大再补索引划算得多。

6. 部署上线与避坑记录：域名、证书、数据库迁移

6.1 部署方式选择：从开发环境到生产环境

开发时用python app.py配合 Flask 自带的 dev server 就够了，但生产环境绝对不能这样跑。我在部署时选择了gunicorn + nginx的组合：

gunicorn -w 4 -b 127.0.0.1:8000 wsgi:app

nginx 负责静态资源、反向代理和 HTTPS 终止，gunicorn 只监听内网端口处理业务请求。4 个 worker 对于这个量级的系统已经比较充裕，如果业务量上来，可以横向加 worker 或部署多实例。另外把DEBUG = False一定要在配置里确认，开发环境下打开调试页面的 Werkzeug 控制台在生产环境就是灾难。

6.2 微信小程序合法域名：最容易卡住的一步

小程序和后端通信有严格限制：wx.request的域名必须在微信公众平台配置为合法域名，并且必须 HTTPS、必须 ICP 备案。我第一次部署时没配域名，直接用 IP 地址加端口访问，小程序端报错说"不在以下 request 合法域名列表中"，折腾了半天才明白问题在哪。

正确做法是：申请一个已备案的域名，配置 HTTPS 证书（Let's Encrypt 免费证书够用），nginx 反代到 gunicorn，然后在微信公众平台的小程序后台，把https://你的域名加入 request 合法域名。这个流程走完后，小程序端才能真正请求到后端接口。真机调试和开发者工具不一样，开发者工具可以勾选"不校验合法域名"，但真机不行，所以测试阶段就最好把域名配好，免得后面临时抱佛脚。

6.3 数据库迁移：Flask-Migrate 的使用和一次教训

项目结构变更、字段调整是很常见的事，手动在数据库里 ALTER TABLE 太容易出错了。我用 Flask-Migrate 管理所有表结构的变更：

flask db init flask db migrate -m "create user and account tables" flask db upgrade

这套流程在本地开发时非常好用，改模型、生成迁移、升级，一气呵成。这里有一个深刻教训：当时我在测试环境直接手动删了一张表想重建，结果没有跑flask db stamp更新迁移版本号，导致后续迁移脚本全部报错。最后只能手动把alembic_version表改回去才恢复。数据库迁移一定要走标准流程，手动改表结构相当于给自己埋雷。

6.4 运行期容易忽略的问题：时区、证书与并发

系统上线运行后，我遇到几个之前没注意的问题。第一个是时区：MySQL 默认用系统时区，Flask 默认用 UTC，如果不统一，流水时间显示和用户本地时间差 8 小时。我统一在 MySQL 连接串里加了?charset=utf8mb4并在 Flask 配置里设TIMEZONE = 'Asia/Shanghai'，同时把所有时间字段设为DateTime类型，保证用户看到的流水时间都是本地时间。

第二个是免费证书的有效期只有 90 天，如果忘记续期，小程序端突然全部请求失败。这个最好加一个自动化任务，或者用支持自动续期的证书方案，避免线上事故。

第三个是并发转账的问题：前面提到的with_for_update()加了行锁，但如果你用错了事务隔离级别，或者在提交阶段忘记 commit，锁会一直持有，后面的请求全部排队超时。我用压测工具模拟了 20 个并发转账请求，确保余额不为负且流水笔数正确之后才上线。

做完整套系统回头看，最有技术含量的部分不是某个高深算法，而是事务的一致性和幂等设计。金融类系统的核心诉求是"钱不能多转、不能少转、不能重复转"，这三条落实到代码层面，就是行锁、Decimal 精度和业务单号唯一约束。这个设计思路不局限于手机银行，任何涉及资金、库存、积分的系统都适用。

最后再分享一个小技巧：开发阶段在 Flask 里加一个模拟登录接口，绕过微信登录流程，直接生成测试 token。这样调试转账和流水功能时可以快速进入业务页面，不用每次都去点小程序授权。等所有业务调通之后，再切回真实登录链路，整个开发效率会提高很多。