简介这份同城物流派送项目源码面向 Android 初学者、课程设计或毕业设计开发者围绕城市即时配送场景串联订单生成、司机抢单、状态流转到送达的完整业务并以 SQLite 完成用户、订单与司机数据的增删改查。压缩包共 275 个文件约 53.42MB包含 31 个 Java 源码、39 个 XML 布局与配置、86 个 class 编译文件及 94 个 PNG 界面素材另有 apk、jar、so 等运行依赖便于导入后梳理工程结构也能对照编译产物理解打包与运行环境。已有 323 人学习下载。读者可参考账号注册登录、自定义适配器绑定订单与司机列表、抢单及配送进度更新、GPS 定位和路线规划等实现思路还能结合完整目录理解 Android 客户端分层、SQLite 持久化与界面资源组织适合按模块拆解学习和二次改造。1. 同城物流派送这类项目最怕的不是并发而是「状态说不清」午高峰刚过客服工位上最常见的一幕不是系统崩了而是用户追问「我这单到哪了」后台订单状态还停在「骑手已接单」而配送员那边说货半小时前就放前台了。同城物流派送的业务量其实不大真正折磨人的是状态、轨迹、责任归属这三件事没有一处可信的落点。这个项目把下单、派单、取货、送达、签收整条链路做成一套可本地跑起来的闭环所有状态变更和位置上报都写进一个 SQLite 文件单机就能演示完整履约过程。它适合想快速搭一套能跑通业务的中小配送团队、做课设的同学以及需要拿一份干净骨架做二次开发的开发者——先把业务跑顺再去谈扩容。2. 项目定位与技术选型为什么同城派送敢拿 SQLite 当主库2.1 业务边界这个项目到底覆盖了哪几段流程先把范围划死不然一个「同城配送」能被需求方塞进整车运输、冷链监控、电子面单打印最后什么都做不深。这份代码守住的是同城即时配送到门这一条主线拆开就是四段用户下单并给出取货点与收货点系统按骑手位置和当前在手单量做派单骑手到店取货、路上按固定间隔上报坐标送达后签收异常情况走取消或改派。四段流程对应四种角色下单方、骑手、调度可以是自动派单也可以人工改派、客服只读查询。项目的接口设计基本是围绕角色切分的/orders面向下单方/couriers面向骑手端上报/dispatch面向调度/track面向查询侧。这种按角色切路由的做法比按数据表切路由更好维护——后期要做权限直接在路由层挂依赖就行不用去动业务代码。需要说清楚的是这个项目不做支付清结算也不做发票订单金额只作为一个字段存下来用于对账展示。这样做的好处是整条链路轻坏处是你接不了真实交易二次开发时如果要接支付得自己在订单状态机里插一个「待支付」前置态这点后面第 6 章会讲。2.2 技术栈盘点Python FastAPI sqlite3 各自负责什么技术栈是 Python 3.10 起步、FastAPI 做 HTTP 层、Pydantic 做入参校验、前端用一份静态页加原生 fetch 调用存储直接落在 Python 标准库的sqlite3上没有引入 ORM。这个组合在同城派送这种「读多写少、单机可承载」的场景里非常合适常见做法是先用标准库把 SQL 写透等数据量或团队规模上来再考虑换 ORM。为什么不直接上 PostgreSQL这是选型里最常被问的一句。我的判断标准是三个数字日订单量在 5000 单以内、并发写入连接不超过 30、单表数据量在千万行以内。这三条都满足时SQLite 开 WAL 模式后的读写表现足够撑住同城派送的峰值而且省掉了数据库运维、连接池配置、备份脚本这一整套东西部署就是拷一个.db文件。反过来如果业务涉及多机房写入、需要行级锁做热点更新、或者要做复杂报表 join那就别硬扛早点换。不引 ORM 也有实际考虑。派单查询里要做「按状态过滤 按距离排序 限制候选数量」这种查询用 ORM 写出来往往变成先查出全表再在内存里过滤性能直接崩。手写 SQL 反而让索引有没有命中一眼可见EXPLAIN QUERY PLAN一跑就知道。代价是字段改名时要全局搜 SQL 字符串所以项目里所有表名和列名都集中定义在schema.sql改一处即可。提示SQLite 版本建议 3.35 以上RETURNING子句和部分 JSON 函数在这个版本之后才稳定项目里的插入后回填自增 ID 用的是RETURNING id低于这个版本会直接报语法错。2.3 数据模型订单、运单、骑手、轨迹四张表怎么咬合数据模型是整个项目的骨架理解它比看接口更重要。四张核心表的关系是一个orders记录用户侧诉求一个shipments记录履约侧的执行单元同城场景通常 1:1但保留 1:N 是为了支持一单多点取送couriers是运力池tracks是骑手坐标流水按shipment_id挂在履约单上。-- schema.sql四张核心表 必要索引 PRAGMA journal_mode WAL; -- 读写并发的基础必须开 PRAGMA foreign_keys ON; CREATE TABLE IF NOT EXISTS orders ( id INTEGER PRIMARY KEY AUTOINCREMENT, order_no TEXT NOT NULL UNIQUE, customer_id TEXT NOT NULL, pickup_addr TEXT NOT NULL, pickup_lng REAL NOT NULL, pickup_lat REAL NOT NULL, drop_addr TEXT NOT NULL, drop_lng REAL NOT NULL, drop_lat REAL NOT NULL, amount_cent INTEGER NOT NULL DEFAULT 0, -- 金额用分存整数避免浮点误差 status TEXT NOT NULL DEFAULT created, created_at INTEGER NOT NULL, -- 毫秒时间戳统一整型 updated_at INTEGER NOT NULL ); CREATE TABLE IF NOT EXISTS shipments ( id INTEGER PRIMARY KEY AUTOINCREMENT, order_id INTEGER NOT NULL REFERENCES orders(id), courier_id INTEGER REFERENCES couriers(id), status TEXT NOT NULL DEFAULT pending, dispatched_at INTEGER, picked_at INTEGER, delivered_at INTEGER, version INTEGER NOT NULL DEFAULT 0, -- 乐观锁版本号 created_at INTEGER NOT NULL ); CREATE TABLE IF NOT EXISTS couriers ( id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT NOT NULL, phone TEXT NOT NULL, status TEXT NOT NULL DEFAULT idle, -- idle / busy / offline cur_lng REAL, cur_lat REAL, load_count INTEGER NOT NULL DEFAULT 0, -- 当前在手单量 updated_at INTEGER NOT NULL ); CREATE TABLE IF NOT EXISTS tracks ( id INTEGER PRIMARY KEY AUTOINCREMENT, shipment_id INTEGER NOT NULL REFERENCES shipments(id), courier_id INTEGER NOT NULL, lng REAL NOT NULL, lat REAL NOT NULL, reported_at INTEGER NOT NULL ); -- 派单时按状态时间过滤这个复合索引是主查询路径 CREATE INDEX IF NOT EXISTS idx_ship_status ON shipments(status, created_at); -- 轨迹按履约单时间倒序取最新点 CREATE INDEX IF NOT EXISTS idx_track_ship_time ON tracks(shipment_id, reported_at DESC); -- 骑手可用性筛选 CREATE INDEX IF NOT EXISTS idx_courier_status ON couriers(status);几个字段的设计意图值得单独讲。amount_cent用整数分存是因为 SQLite 的REAL是 IEEE754 双精度累加对账时会出分位误差这种坑在财务口径上没法解释。created_at统一用毫秒整型而不是TEXT存 ISO 时间原因是字符串比较虽然也能用但一遇到时区混用就全乱而且整型索引体积更小、范围查询更快。shipments.version是乐观锁的版本号第 4 章讲并发更新时会用到它。couriers表上的load_count是一个反范式字段理论上可以实时COUNT(*)算出来但派单是高频路径每次派单去数一遍在手单量会让派单接口从毫秒级掉到几十毫秒。用冗余字段换读性能代价是每次接单、送达都要同步维护它项目里把这两处更新包在同一个事务里保证不会飘。tracks表故意不加外键级联删除是因为轨迹属于审计数据订单删了轨迹也要留着。实际项目里这张表增长最快第 4 章会给一个攒批写入的方案第 5 章会讲它变大之后列表页为什么突然变慢。3. 目录结构与启动链路从解压到第一单跑通3.1 目录树每个文件负责哪一段拿到这份代码先别急着pip install花两分钟看一眼目录后面调试能省一半时间。整体是典型的 FastAPI 小项目布局不搞过度分层每个文件职责单一city-delivery/ ├── app/ │ ├── main.py # FastAPI 实例、路由挂载、启动钩子 │ ├── db.py # 连接管理、PRAGMA 设置、事务上下文 │ ├── models.py # Pydantic 入参/出参模型 │ ├── state_machine.py # 订单与履约单的合法状态迁移表 │ ├── dispatch.py # 派单打分与候选骑手筛选 │ ├── routes/ │ │ ├── orders.py # 下单、查询、取消 │ │ ├── couriers.py # 骑手上下线、位置上报 │ │ └── dispatch.py # 手动派单、改派、签收 │ └── static/ │ └── index.html # 单页演示原生 fetch 调接口 ├── schema.sql # 建表与索引幂等可重复执行 ├── seed.py # 灌入演示骑手与历史订单 ├── requirements.txt └── README.mddb.py是整个项目的关键文件所有连接都从这里出PRAGMA 设置只写一遍避免某个路由自己sqlite3.connect()忘了开 WAL 导致锁表。state_machine.py单独抽出来是个好习惯状态迁移规则是业务里最容易改的部分集中在一处测试也好写。routes/按角色切分而不是按表切分前面已经说过理由。3.2 建库与初始化schema.sql 一把梭环境准备没什么花样Python 版本对上就行。虚拟环境建好后装依赖然后把建表脚本跑一遍。schema.sql里所有语句都带IF NOT EXISTS重复执行不会报错这点在反复调试时很救命。python -m venv .venv source .venv/bin/activate # Windows 用 .venv\Scripts\activate pip install fastapi uvicorn pydantic # 建库DB 文件默认落在 ./delivery.db sqlite3 delivery.db schema.sql # 灌演示数据8 个骑手 20 条历史订单 python seed.pyseed.py里灌骑手时会把坐标随机撒在配送站周边三公里范围内这么做是为了让派单算法有得算——骑手全挤在一个点上距离项权重就失效了你测不出打分函数是否正常。灌历史订单时故意留了几条状态卡在picked的单用来验证「长时间未送达」的告警查询能不能捞出来。注意seed.py默认会先清空三张业务表再写只适合开发环境。如果库里有你自己造的数据跑之前先把delivery.db备份一份别问我怎么知道要提醒这一句。3.3 启动与第一单三个请求验证整条链路启动命令很简单--reload开着方便改代码uvicorn app.main:app --reload --port 8000起来之后别直接开浏览器先用 curl 把主链路走一遍出问题的时候报错信息比前端控制台清楚得多。三个请求分别是下单、查可用骑手、派单# 1. 下单取货点和收货点用经纬度表示 curl -X POST http://127.0.0.1:8000/orders \ -H Content-Type: application/json \ -d { customer_id: u_1001, pickup_addr: 模拟项目A座前台, pickup_lng: 116.404, pickup_lat: 39.915, drop_addr: 模拟项目B座 1203, drop_lng: 116.418, drop_lat: 39.921, amount_cent: 1850 } # 2. 查当前可派骑手返回按距离升序的候选列表 curl http://127.0.0.1:8000/couriers/available?lng116.404lat39.915limit5 # 3. 对订单发起派单 curl -X POST http://127.0.0.1:8000/dispatch/auto \ -H Content-Type: application/json \ -d {order_no: 返回的订单号}第一步返回体里会带order_no和初始状态created第二步拿到候选骑手列表正常情况下应该按距离从近到远排第三步成功后订单状态变dispatchedshipments表里多一条记录couriers.load_count加一。这三个动作串起来就说明表结构、路由、事务、索引全通了。如果第三步返回 409八成是候选骑手全被占了去看couriers表里status是不是还有idle的。如果返回 500 且日志里有database is locked去检查db.py里的busy_timeout有没有生效第 5 章第一条就是讲这个。前端页面在http://127.0.0.1:8000/static/index.html就是个列表加几个按钮能看到订单状态流转和骑手位置用来演示足够了。它不是重点但拿来给非技术同事看效果很好用省得你截图贴文档。4. 核心模块拆解状态机、派单打分与 SQLite 并发写入4.1 状态机把「谁能改成谁」写死在一张表里订单状态混乱是同城派送项目里最典型的翻车现场。表现是数据库里出现delivered又变回dispatched的单或者已取消的订单被骑手点了送达。根因就一个状态更新散落在各个接口里每个地方UPDATE ... SET status?没有任何校验。这个项目的做法是把合法迁移写成一张字典所有状态变更必须过一道校验函数# app/state_machine.py # 键是当前状态值是允许迁移到的目标状态集合 ORDER_TRANSITIONS { created: {dispatched, cancelled}, dispatched: {picked, cancelled, redispatch}, picked: {delivered, redispatch}, delivered: set(), # 终态不允许再改 cancelled: set(), } class InvalidTransition(Exception): pass def assert_transition(current: str, target: str) - None: 校验状态迁移是否合法非法直接抛异常由路由层转 409 allowed ORDER_TRANSITIONS.get(current) if allowed is None: raise InvalidTransition(f未知状态: {current}) if target not in allowed: raise InvalidTransition(f不允许从 {current} 迁移到 {target})ORDER_TRANSITIONS是唯一的真相来源新增状态只改这里不用满项目搜status 。assert_transition只做校验不做写入这样它可以在写库前调用避免开了一个事务又因为非法迁移回滚。终态用空集合set()表示比写if status in (delivered, cancelled): raise更省事加新终态时不用改判断逻辑。实际更新时还要配合乐观锁防止两个请求同时读到dispatched都往picked改# app/routes/dispatch.py 片段 def update_shipment_status(conn, shipment_id: int, target: str, expected_ver: int): cur conn.execute( UPDATE shipments SET status ?, version version 1 WHERE id ? AND version ?, # 版本号对不上就更新 0 行 (target, shipment_id, expected_ver), ) if cur.rowcount 0: raise InvalidTransition(状态已被其他请求修改请刷新后重试)WHERE id ? AND version ?这一句是乐观锁的核心rowcount 0意味着在你读取之后有人抢先改了这时候抛异常让前端重试比默默覆盖安全得多。version version 1保证每次成功更新版本都递增形成单调序列排查问题时看版本号跳变次数就知道这单被改过几次。4.2 派单打分距离、在手单量、静默时长三项加权派单算法的目标不是「找最近的」而是「找最合适的」。纯按距离派会把所有单压给站点门口那个骑手十分钟后他手里二十单全超时。项目的打分函数用三项加权# app/dispatch.py import math def haversine_km(lng1, lat1, lng2, lat2) - float: 球面距离单位公里。同城范围误差可忽略 r 6371.0 p1, p2 math.radians(lat1), math.radians(lat2) dp p2 - p1 dl math.radians(lng2 - lng1) a math.sin(dp / 2) ** 2 math.cos(p1) * math.cos(p2) * math.sin(dl / 2) ** 2 return 2 * r * math.asin(math.sqrt(a)) def score(courier, pickup_lng, pickup_lat, now_ms) - float: 分数越低越优先。三项取货距离、在手单量、静默时长 dist haversine_km(courier[cur_lng], courier[cur_lat], pickup_lng, pickup_lat) idle_ms now_ms - courier[updated_at] return ( 1.0 * dist # 每公里记 1 分 0.8 * courier[load_count] # 每在手一单记 0.8 分 - 0.3 * min(idle_ms / 60000, 30) # 静默每分钟减 0.3 分封顶 30 分钟 )三个权重是可以调的1.0的距离权重调大派单更偏近0.8的负载权重调大更偏向均摊-0.3的静默项是为了让长时间没接到单的骑手获得补偿min(..., 30)封顶是为了防止一个挂机两小时的骑手靠静默分刷到最前面。这个封顶是血泪经验早期没封顶的时候有人把骑手端挂着不管系统一直给他派单他全拒。筛选候选骑手放在 SQL 里做别把全表捞到内存再过滤# 候选池只取在线且有承载余量的最多 200 个进内存打分 rows conn.execute( SELECT id, cur_lng, cur_lat, load_count, updated_at FROM couriers WHERE status idle AND load_count ? ORDER BY updated_at DESC LIMIT 200, (MAX_LOAD,), ).fetchall()MAX_LOAD是单骑手承载上限同城场景常见设 5 到 8超过就不再派。LIMIT 200是一道保险防止某次数据异常把几万个骑手全捞出来打分。ORDER BY updated_at DESC让最近活跃的骑手优先进入候选池比随机截断合理。派单成功后要在同一个事务里做三件事更新shipments、更新couriers.load_count和status、写一条派单日志。这三步必须原子否则会出现骑手负载加了但履约单没建出来的脏数据。4.3 SQLite 并发写入WAL、busy_timeout 与事务边界SQLite 被诟病最多的就是并发写但绝大部分「database is locked」不是 SQLite 的问题是连接没配对。这个项目的连接工厂长这样# app/db.py import sqlite3 from contextlib import contextmanager DB_PATH delivery.db def get_conn() - sqlite3.Connection: conn sqlite3.connect(DB_PATH, timeout5.0, isolation_levelNone) conn.row_factory sqlite3.Row # 让查询结果能按列名取值 conn.execute(PRAGMA journal_mode WAL) # 读写不互斥 conn.execute(PRAGMA synchronous NORMAL) # WAL 下这个档位足够安全 conn.execute(PRAGMA busy_timeout 5000) # 锁等待 5 秒再报错 conn.execute(PRAGMA foreign_keys ON) return conn contextmanager def transaction(): 显式事务正常提交异常回滚 conn get_conn() try: conn.execute(BEGIN IMMEDIATE) # 立刻拿写锁避免升级锁时死等 yield conn conn.execute(COMMIT) except Exception: conn.execute(ROLLBACK) raise finally: conn.close()journal_mode WAL是读写并发的基石开了之后读操作不会被写操作阻塞同城派送里「骑手上报位置」和「客服查订单」可以同时进行。synchronous NORMAL在 WAL 模式下意味着崩溃可能丢最后几个事务但不会损坏数据库文件对配送场景是可接受的取舍如果业务不能接受丢单改成FULL代价是每次提交都要 fsync写入吞吐会掉一个量级。BEGIN IMMEDIATE是最容易被忽略的一行。默认的BEGIN DEFERRED是等到第一条写语句才尝试拿锁如果事务里先读后写可能在中途才发现拿不到写锁这时要处理锁升级失败逻辑很绕。IMMEDIATE一开始就拿写锁拿不到直接按busy_timeout等待行为可预测得多。isolation_levelNone是关掉 Python 的隐式事务管理让事务边界完全由代码里的BEGIN/COMMIT控制。不关的话sqlite3模块会自作主张在某些语句前开事务和你手写的BEGIN撞车报「cannot start a transaction within a transaction」。提示busy_timeout不是越大越好。设到 30 秒请求会一直挂着不返回前端以为超时重试反而把压力放大。5 秒是个比较平衡的值超过这个时间基本说明有长事务在跑该去查是谁了。4.4 轨迹落库高频写入用攒批别一条一条插骑手端一般 3 到 5 秒上报一次坐标100 个骑手在线就是每秒 20 到 30 次插入每次都单独开事务的话SQLite 的 fsync 开销会把磁盘打满。项目里的做法是内存攒批攒够条数或到时间窗口再一次性executemany# app/track_buffer.py import time, threading class TrackBuffer: def __init__(self, conn_factory, batch_size200, flush_interval1.0): self._buf [] self._lock threading.Lock() self._conn_factory conn_factory self._batch_size batch_size self._interval flush_interval def add(self, shipment_id, courier_id, lng, lat): with self._lock: self._buf.append((shipment_id, courier_id, lng, lat, int(time.time() * 1000))) if len(self._buf) self._batch_size: self._flush_locked() def _flush_locked(self): if not self._buf: return rows, self._buf self._buf, [] with self._conn_factory() as conn: conn.executemany( INSERT INTO tracks(shipment_id, courier_id, lng, lat, reported_at) VALUES (?, ?, ?, ?, ?), rows ) def flush_loop(self): 后台线程按固定间隔兜底刷盘防止低峰期数据一直压在内存 while True: time.sleep(self._interval) with self._lock: self._flush_locked()batch_size 200是权衡后的值太小起不到攒批效果太大则内存里压的数据多进程被 kill 时丢的轨迹也多。flush_interval 1.0保证低峰期即使一个骑手都没上报内存里那几条也会在一秒内落库客服查轨迹不会看到延迟。executemany在 SQLite 里会被包成单条事务执行200 条插入的 fsync 次数从 200 次降到 1 次实测写入吞吐能差一个数量级。这个方案的代价是进程异常退出会丢最后一批数据。同城派送的轨迹属于「少几个点不影响判责」的数据可以接受如果业务要求轨迹零丢失那就得改成写本地日志文件再回放复杂度会上去不少。5. 避坑与排查SQLite 在同城派送场景的五个真实坑5.1 坑一一压测就database is locked现象本地单请求跑得好好的一上 20 并发压测日志里刷屏sqlite3.OperationalError: database is locked接口大面积 500。原因两个层面的问题叠在一起。一是连接没开 WAL默认的 rollback journal 模式下写操作会独占整库二是 Pythonsqlite3的默认timeout是 5 秒但很多人建连接时只写了sqlite3.connect(path)没意识到某些框架封装里timeout被改成了 0一撞锁立刻抛异常不等待。解决统一走db.py的连接工厂确保PRAGMA journal_mode WAL、PRAGMA busy_timeout 5000、timeout5.0三处都设上。另外把长事务拆短尤其别在一个事务里做 HTTP 调用比如派单时同步调地图 API 算路线网络一慢写锁就被人攥着不放。5.2 坑二时间字段存成字符串范围查询走不了索引现象订单列表按时间倒序查前一万条还行到十万条时接口从 30ms 涨到 800msEXPLAIN QUERY PLAN显示全表扫描。原因早期建表时把created_at写成TEXT存2024-05-01 10:00:00查询时用WHERE created_at 2024-05-01做字符串比较。逻辑上能跑通但一旦表里混进不同格式有的带毫秒、有的带时区后缀索引的有序性就用不上了优化器直接放弃索引改全扫。解决时间统一存毫秒整型索引建在整型列上。已有数据用一次性迁移脚本转换UPDATE orders SET created_at CAST(strftime(%s, created_at) AS INTEGER) * 1000。转换前先备份转换后用EXPLAIN QUERY PLAN确认走了idx_ship_status。5.3 坑三两个骑手同时点「接单」同一单被派了两次现象调度后台看到一条履约单关联了两个骑手两个骑手都以为自己接了这单跑到店里撞上。原因派单逻辑是先SELECT查可派骑手再UPDATE写入中间没有原子性。两个请求几乎同时进来都查到了同一个空闲骑手都执行了更新后写的覆盖先写的但前端两个都收到了成功。这是经典的丢失更新。解决改条件更新把「骑手是否空闲」作为WHERE条件的一部分靠rowcount判断抢没抢到cur conn.execute( UPDATE couriers SET statusbusy, load_countload_count1 WHERE id? AND statusidle, (courier_id,) ) if cur.rowcount 0: # 没抢到换下一个候选骑手重试 return try_next_candidate()rowcount 0说明在你读取之后这个骑手已经被别人占了直接换下一个候选不要重试同一个。这一步必须和shipments的插入在同一个BEGIN IMMEDIATE事务里否则还是会有中间态。5.4 坑四轨迹表涨到两千万行履约详情页打不开现象上线三个月后查单个订单的轨迹列表要 3 秒以上页面直接转圈超时。原因tracks表只有主键索引查询语句是SELECT * FROM tracks WHERE shipment_id ? ORDER BY reported_at DESC。没有联合索引SQLite 只能扫全表再排序表越大越慢而且SELECT *把每行都读出来磁盘 IO 也扛不住。解决建(shipment_id, reported_at DESC)的联合索引覆盖过滤和排序两个动作一次索引扫描就能按序返回。同时把SELECT *改成只取需要的列。已经很大的表补索引用CREATE INDEX会锁库低峰期执行或者在维护窗口用「建新表 灌数据 改名」的方式做在线迁移。长期方案是按月分表把历史轨迹归档到tracks_202405这类表里主表只留最近三个月。5.5 坑五直接cp delivery.db备份恢复后数据不全现象运维同学每天定时cp delivery.db backup/某次机房迁移后恢复发现最近几小时的单全没了甚至有一次库文件直接打不开。原因开了 WAL 之后最近提交的数据还在delivery.db-wal文件里没有 checkpoint 回主库。只拷.db不拷-wal和-shm等于拷了个半成品如果在写入过程中直接cp还可能拷到事务进行中的中间状态文件级损坏。解决备份必须走 SQLite 官方提供的在线备份接口或者用VACUUM INTO# 方式一在线备份不阻塞读写得到的是完整一致快照 sqlite3 delivery.db .backup backup/delivery_$(date %Y%m%d_%H%M).db # 方式二VACUUM INTO顺带整理碎片只读操作 sqlite3 delivery.db VACUUM INTO backup/delivery_clean.db如果非要用文件拷贝先执行PRAGMA wal_checkpoint(TRUNCATE)把 WAL 刷回主库停写之后再cp三个文件.db-wal-shm一起拷。但既然有.backup命令就别折腾文件拷贝了一行命令的事。6. 二次开发从单机版走向可切换存储与多运力6.1 先抽仓储层为换库留一个口子单机版跑顺之后第一个要动的地方是存储。别等到真换 PostgreSQL 那天才发现 SQL 散落在二十个路由文件里。做法是先抽一层仓储接口把「查候选骑手」「抢骑手」「写轨迹」这些动作定义成方法路由只调方法不写 SQL# app/repo/base.py class CourierRepo: def list_available(self, max_load: int, limit: int 200): ... def try_occupy(self, courier_id: int) - bool: ... # 返回是否抢到 # app/repo/sqlite_repo.py class SqliteCourierRepo(CourierRepo): def try_occupy(self, courier_id): cur self.conn.execute( UPDATE couriers SET statusbusy, load_countload_count1 WHERE id? AND statusidle, (courier_id,) ) return cur.rowcount 1try_occupy返回布尔值而不是抛异常是为了让上层派单逻辑能自然地做「换下一个候选」的循环不用写 try/except 控制流。抽完这层把main.py里的依赖注入指向SqliteCourierRepo将来写一个PgCourierRepo改一行配置就能切不需要动业务代码。6.2 加运力属性大件、保温箱、载重上限同城派送往上做一步必然会遇到「这单是 20 公斤的水普通电动车拉不了」。改造点有两处couriers表加vehicle_typeebike / van、max_weight_kg、has_insulation三个字段派单候选池的 SQL 里加过滤条件。ALTER TABLE couriers ADD COLUMN vehicle_type TEXT NOT NULL DEFAULT ebike; ALTER TABLE couriers ADD COLUMN max_weight_kg REAL NOT NULL DEFAULT 20; ALTER TABLE couriers ADD COLUMN has_insulation INTEGER NOT NULL DEFAULT 0; -- 订单侧也要记录运力需求否则没法匹配 ALTER TABLE orders ADD COLUMN weight_kg REAL NOT NULL DEFAULT 1; ALTER TABLE orders ADD COLUMN need_insulation INTEGER NOT NULL DEFAULT 0;候选池查询改成WHERE statusidle AND load_count ? AND max_weight_kg ?保温需求再加一条AND has_insulation 1。注意 ALTER TABLE 加带默认值的非空列在 SQLite 里是支持的大表上会因为改写每一行而变慢几百万行以上建议用「建新表 灌数据 改名」的方式别在业务高峰期直接跑。6.3 验证方法先写状态机单测再压派单接口改完之后怎么确认没改坏两个层面。状态机层面写参数化单测把所有合法和非法迁移对都覆盖一遍跑得快、回归成本低。派单层面写一个简单的并发脚本起 50 个线程同时抢同一批订单断言每个订单最终只对应一个骑手、load_count总和等于成功派单数。这个断言能抓住绝大多数事务边界没写对的问题。import pytest from app.state_machine import assert_transition, InvalidTransition pytest.mark.parametrize(cur,tgt, [ (created, dispatched), (picked, delivered), (dispatched, picked), ]) def test_legal(cur, tgt): assert_transition(cur, tgt) # 不抛异常即通过 pytest.mark.parametrize(cur,tgt, [ (delivered, dispatched), (cancelled, picked), (unknown, picked), ]) def test_illegal(cur, tgt): with pytest.raises(InvalidTransition): assert_transition(cur, tgt)这套测试写下来不到一百行但每次改状态机都会帮你挡一次。我一般还会在 CI 里加一条sqlite3 delivery.db PRAGMA integrity_check;输出不是ok就直接挂掉构建。顺便说个改造顺序上的建议先抽仓储层再加字段最后动派单打分。反过来做的话你会在一堆散落的 SQL 里改字段名改到怀疑人生。派单权重这种参数最好抽到配置文件里配合一个小的 A/B 开关线上调权重的时候不用发版。从那以后我每次给这类项目做改造都强制先跑一遍状态机单测再动派单逻辑顺序一乱就得花两倍时间找回滚点。希望帮到你。本文还有配套的精品资源点击获取
简介这份同城物流派送项目源码面向 Android 初学者、课程设计或毕业设计开发者围绕城市即时配送场景串联订单生成、司机抢单、状态流转到送达的完整业务并以 SQLite 完成用户、订单与司机数据的增删改查。压缩包共 275 个文件约 53.42MB包含 31 个 Java 源码、39 个 XML 布局与配置、86 个 class 编译文件及 94 个 PNG 界面素材另有 apk、jar、so 等运行依赖便于导入后梳理工程结构也能对照编译产物理解打包与运行环境。已有 323 人学习下载。读者可参考账号注册登录、自定义适配器绑定订单与司机列表、抢单及配送进度更新、GPS 定位和路线规划等实现思路还能结合完整目录理解 Android 客户端分层、SQLite 持久化与界面资源组织适合按模块拆解学习和二次改造。1. 同城物流派送这类项目最怕的不是并发而是「状态说不清」午高峰刚过客服工位上最常见的一幕不是系统崩了而是用户追问「我这单到哪了」后台订单状态还停在「骑手已接单」而配送员那边说货半小时前就放前台了。同城物流派送的业务量其实不大真正折磨人的是状态、轨迹、责任归属这三件事没有一处可信的落点。这个项目把下单、派单、取货、送达、签收整条链路做成一套可本地跑起来的闭环所有状态变更和位置上报都写进一个 SQLite 文件单机就能演示完整履约过程。它适合想快速搭一套能跑通业务的中小配送团队、做课设的同学以及需要拿一份干净骨架做二次开发的开发者——先把业务跑顺再去谈扩容。2. 项目定位与技术选型为什么同城派送敢拿 SQLite 当主库2.1 业务边界这个项目到底覆盖了哪几段流程先把范围划死不然一个「同城配送」能被需求方塞进整车运输、冷链监控、电子面单打印最后什么都做不深。这份代码守住的是同城即时配送到门这一条主线拆开就是四段用户下单并给出取货点与收货点系统按骑手位置和当前在手单量做派单骑手到店取货、路上按固定间隔上报坐标送达后签收异常情况走取消或改派。四段流程对应四种角色下单方、骑手、调度可以是自动派单也可以人工改派、客服只读查询。项目的接口设计基本是围绕角色切分的/orders面向下单方/couriers面向骑手端上报/dispatch面向调度/track面向查询侧。这种按角色切路由的做法比按数据表切路由更好维护——后期要做权限直接在路由层挂依赖就行不用去动业务代码。需要说清楚的是这个项目不做支付清结算也不做发票订单金额只作为一个字段存下来用于对账展示。这样做的好处是整条链路轻坏处是你接不了真实交易二次开发时如果要接支付得自己在订单状态机里插一个「待支付」前置态这点后面第 6 章会讲。2.2 技术栈盘点Python FastAPI sqlite3 各自负责什么技术栈是 Python 3.10 起步、FastAPI 做 HTTP 层、Pydantic 做入参校验、前端用一份静态页加原生 fetch 调用存储直接落在 Python 标准库的sqlite3上没有引入 ORM。这个组合在同城派送这种「读多写少、单机可承载」的场景里非常合适常见做法是先用标准库把 SQL 写透等数据量或团队规模上来再考虑换 ORM。为什么不直接上 PostgreSQL这是选型里最常被问的一句。我的判断标准是三个数字日订单量在 5000 单以内、并发写入连接不超过 30、单表数据量在千万行以内。这三条都满足时SQLite 开 WAL 模式后的读写表现足够撑住同城派送的峰值而且省掉了数据库运维、连接池配置、备份脚本这一整套东西部署就是拷一个.db文件。反过来如果业务涉及多机房写入、需要行级锁做热点更新、或者要做复杂报表 join那就别硬扛早点换。不引 ORM 也有实际考虑。派单查询里要做「按状态过滤 按距离排序 限制候选数量」这种查询用 ORM 写出来往往变成先查出全表再在内存里过滤性能直接崩。手写 SQL 反而让索引有没有命中一眼可见EXPLAIN QUERY PLAN一跑就知道。代价是字段改名时要全局搜 SQL 字符串所以项目里所有表名和列名都集中定义在schema.sql改一处即可。提示SQLite 版本建议 3.35 以上RETURNING子句和部分 JSON 函数在这个版本之后才稳定项目里的插入后回填自增 ID 用的是RETURNING id低于这个版本会直接报语法错。2.3 数据模型订单、运单、骑手、轨迹四张表怎么咬合数据模型是整个项目的骨架理解它比看接口更重要。四张核心表的关系是一个orders记录用户侧诉求一个shipments记录履约侧的执行单元同城场景通常 1:1但保留 1:N 是为了支持一单多点取送couriers是运力池tracks是骑手坐标流水按shipment_id挂在履约单上。-- schema.sql四张核心表 必要索引 PRAGMA journal_mode WAL; -- 读写并发的基础必须开 PRAGMA foreign_keys ON; CREATE TABLE IF NOT EXISTS orders ( id INTEGER PRIMARY KEY AUTOINCREMENT, order_no TEXT NOT NULL UNIQUE, customer_id TEXT NOT NULL, pickup_addr TEXT NOT NULL, pickup_lng REAL NOT NULL, pickup_lat REAL NOT NULL, drop_addr TEXT NOT NULL, drop_lng REAL NOT NULL, drop_lat REAL NOT NULL, amount_cent INTEGER NOT NULL DEFAULT 0, -- 金额用分存整数避免浮点误差 status TEXT NOT NULL DEFAULT created, created_at INTEGER NOT NULL, -- 毫秒时间戳统一整型 updated_at INTEGER NOT NULL ); CREATE TABLE IF NOT EXISTS shipments ( id INTEGER PRIMARY KEY AUTOINCREMENT, order_id INTEGER NOT NULL REFERENCES orders(id), courier_id INTEGER REFERENCES couriers(id), status TEXT NOT NULL DEFAULT pending, dispatched_at INTEGER, picked_at INTEGER, delivered_at INTEGER, version INTEGER NOT NULL DEFAULT 0, -- 乐观锁版本号 created_at INTEGER NOT NULL ); CREATE TABLE IF NOT EXISTS couriers ( id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT NOT NULL, phone TEXT NOT NULL, status TEXT NOT NULL DEFAULT idle, -- idle / busy / offline cur_lng REAL, cur_lat REAL, load_count INTEGER NOT NULL DEFAULT 0, -- 当前在手单量 updated_at INTEGER NOT NULL ); CREATE TABLE IF NOT EXISTS tracks ( id INTEGER PRIMARY KEY AUTOINCREMENT, shipment_id INTEGER NOT NULL REFERENCES shipments(id), courier_id INTEGER NOT NULL, lng REAL NOT NULL, lat REAL NOT NULL, reported_at INTEGER NOT NULL ); -- 派单时按状态时间过滤这个复合索引是主查询路径 CREATE INDEX IF NOT EXISTS idx_ship_status ON shipments(status, created_at); -- 轨迹按履约单时间倒序取最新点 CREATE INDEX IF NOT EXISTS idx_track_ship_time ON tracks(shipment_id, reported_at DESC); -- 骑手可用性筛选 CREATE INDEX IF NOT EXISTS idx_courier_status ON couriers(status);几个字段的设计意图值得单独讲。amount_cent用整数分存是因为 SQLite 的REAL是 IEEE754 双精度累加对账时会出分位误差这种坑在财务口径上没法解释。created_at统一用毫秒整型而不是TEXT存 ISO 时间原因是字符串比较虽然也能用但一遇到时区混用就全乱而且整型索引体积更小、范围查询更快。shipments.version是乐观锁的版本号第 4 章讲并发更新时会用到它。couriers表上的load_count是一个反范式字段理论上可以实时COUNT(*)算出来但派单是高频路径每次派单去数一遍在手单量会让派单接口从毫秒级掉到几十毫秒。用冗余字段换读性能代价是每次接单、送达都要同步维护它项目里把这两处更新包在同一个事务里保证不会飘。tracks表故意不加外键级联删除是因为轨迹属于审计数据订单删了轨迹也要留着。实际项目里这张表增长最快第 4 章会给一个攒批写入的方案第 5 章会讲它变大之后列表页为什么突然变慢。3. 目录结构与启动链路从解压到第一单跑通3.1 目录树每个文件负责哪一段拿到这份代码先别急着pip install花两分钟看一眼目录后面调试能省一半时间。整体是典型的 FastAPI 小项目布局不搞过度分层每个文件职责单一city-delivery/ ├── app/ │ ├── main.py # FastAPI 实例、路由挂载、启动钩子 │ ├── db.py # 连接管理、PRAGMA 设置、事务上下文 │ ├── models.py # Pydantic 入参/出参模型 │ ├── state_machine.py # 订单与履约单的合法状态迁移表 │ ├── dispatch.py # 派单打分与候选骑手筛选 │ ├── routes/ │ │ ├── orders.py # 下单、查询、取消 │ │ ├── couriers.py # 骑手上下线、位置上报 │ │ └── dispatch.py # 手动派单、改派、签收 │ └── static/ │ └── index.html # 单页演示原生 fetch 调接口 ├── schema.sql # 建表与索引幂等可重复执行 ├── seed.py # 灌入演示骑手与历史订单 ├── requirements.txt └── README.mddb.py是整个项目的关键文件所有连接都从这里出PRAGMA 设置只写一遍避免某个路由自己sqlite3.connect()忘了开 WAL 导致锁表。state_machine.py单独抽出来是个好习惯状态迁移规则是业务里最容易改的部分集中在一处测试也好写。routes/按角色切分而不是按表切分前面已经说过理由。3.2 建库与初始化schema.sql 一把梭环境准备没什么花样Python 版本对上就行。虚拟环境建好后装依赖然后把建表脚本跑一遍。schema.sql里所有语句都带IF NOT EXISTS重复执行不会报错这点在反复调试时很救命。python -m venv .venv source .venv/bin/activate # Windows 用 .venv\Scripts\activate pip install fastapi uvicorn pydantic # 建库DB 文件默认落在 ./delivery.db sqlite3 delivery.db schema.sql # 灌演示数据8 个骑手 20 条历史订单 python seed.pyseed.py里灌骑手时会把坐标随机撒在配送站周边三公里范围内这么做是为了让派单算法有得算——骑手全挤在一个点上距离项权重就失效了你测不出打分函数是否正常。灌历史订单时故意留了几条状态卡在picked的单用来验证「长时间未送达」的告警查询能不能捞出来。注意seed.py默认会先清空三张业务表再写只适合开发环境。如果库里有你自己造的数据跑之前先把delivery.db备份一份别问我怎么知道要提醒这一句。3.3 启动与第一单三个请求验证整条链路启动命令很简单--reload开着方便改代码uvicorn app.main:app --reload --port 8000起来之后别直接开浏览器先用 curl 把主链路走一遍出问题的时候报错信息比前端控制台清楚得多。三个请求分别是下单、查可用骑手、派单# 1. 下单取货点和收货点用经纬度表示 curl -X POST http://127.0.0.1:8000/orders \ -H Content-Type: application/json \ -d { customer_id: u_1001, pickup_addr: 模拟项目A座前台, pickup_lng: 116.404, pickup_lat: 39.915, drop_addr: 模拟项目B座 1203, drop_lng: 116.418, drop_lat: 39.921, amount_cent: 1850 } # 2. 查当前可派骑手返回按距离升序的候选列表 curl http://127.0.0.1:8000/couriers/available?lng116.404lat39.915limit5 # 3. 对订单发起派单 curl -X POST http://127.0.0.1:8000/dispatch/auto \ -H Content-Type: application/json \ -d {order_no: 返回的订单号}第一步返回体里会带order_no和初始状态created第二步拿到候选骑手列表正常情况下应该按距离从近到远排第三步成功后订单状态变dispatchedshipments表里多一条记录couriers.load_count加一。这三个动作串起来就说明表结构、路由、事务、索引全通了。如果第三步返回 409八成是候选骑手全被占了去看couriers表里status是不是还有idle的。如果返回 500 且日志里有database is locked去检查db.py里的busy_timeout有没有生效第 5 章第一条就是讲这个。前端页面在http://127.0.0.1:8000/static/index.html就是个列表加几个按钮能看到订单状态流转和骑手位置用来演示足够了。它不是重点但拿来给非技术同事看效果很好用省得你截图贴文档。4. 核心模块拆解状态机、派单打分与 SQLite 并发写入4.1 状态机把「谁能改成谁」写死在一张表里订单状态混乱是同城派送项目里最典型的翻车现场。表现是数据库里出现delivered又变回dispatched的单或者已取消的订单被骑手点了送达。根因就一个状态更新散落在各个接口里每个地方UPDATE ... SET status?没有任何校验。这个项目的做法是把合法迁移写成一张字典所有状态变更必须过一道校验函数# app/state_machine.py # 键是当前状态值是允许迁移到的目标状态集合 ORDER_TRANSITIONS { created: {dispatched, cancelled}, dispatched: {picked, cancelled, redispatch}, picked: {delivered, redispatch}, delivered: set(), # 终态不允许再改 cancelled: set(), } class InvalidTransition(Exception): pass def assert_transition(current: str, target: str) - None: 校验状态迁移是否合法非法直接抛异常由路由层转 409 allowed ORDER_TRANSITIONS.get(current) if allowed is None: raise InvalidTransition(f未知状态: {current}) if target not in allowed: raise InvalidTransition(f不允许从 {current} 迁移到 {target})ORDER_TRANSITIONS是唯一的真相来源新增状态只改这里不用满项目搜status 。assert_transition只做校验不做写入这样它可以在写库前调用避免开了一个事务又因为非法迁移回滚。终态用空集合set()表示比写if status in (delivered, cancelled): raise更省事加新终态时不用改判断逻辑。实际更新时还要配合乐观锁防止两个请求同时读到dispatched都往picked改# app/routes/dispatch.py 片段 def update_shipment_status(conn, shipment_id: int, target: str, expected_ver: int): cur conn.execute( UPDATE shipments SET status ?, version version 1 WHERE id ? AND version ?, # 版本号对不上就更新 0 行 (target, shipment_id, expected_ver), ) if cur.rowcount 0: raise InvalidTransition(状态已被其他请求修改请刷新后重试)WHERE id ? AND version ?这一句是乐观锁的核心rowcount 0意味着在你读取之后有人抢先改了这时候抛异常让前端重试比默默覆盖安全得多。version version 1保证每次成功更新版本都递增形成单调序列排查问题时看版本号跳变次数就知道这单被改过几次。4.2 派单打分距离、在手单量、静默时长三项加权派单算法的目标不是「找最近的」而是「找最合适的」。纯按距离派会把所有单压给站点门口那个骑手十分钟后他手里二十单全超时。项目的打分函数用三项加权# app/dispatch.py import math def haversine_km(lng1, lat1, lng2, lat2) - float: 球面距离单位公里。同城范围误差可忽略 r 6371.0 p1, p2 math.radians(lat1), math.radians(lat2) dp p2 - p1 dl math.radians(lng2 - lng1) a math.sin(dp / 2) ** 2 math.cos(p1) * math.cos(p2) * math.sin(dl / 2) ** 2 return 2 * r * math.asin(math.sqrt(a)) def score(courier, pickup_lng, pickup_lat, now_ms) - float: 分数越低越优先。三项取货距离、在手单量、静默时长 dist haversine_km(courier[cur_lng], courier[cur_lat], pickup_lng, pickup_lat) idle_ms now_ms - courier[updated_at] return ( 1.0 * dist # 每公里记 1 分 0.8 * courier[load_count] # 每在手一单记 0.8 分 - 0.3 * min(idle_ms / 60000, 30) # 静默每分钟减 0.3 分封顶 30 分钟 )三个权重是可以调的1.0的距离权重调大派单更偏近0.8的负载权重调大更偏向均摊-0.3的静默项是为了让长时间没接到单的骑手获得补偿min(..., 30)封顶是为了防止一个挂机两小时的骑手靠静默分刷到最前面。这个封顶是血泪经验早期没封顶的时候有人把骑手端挂着不管系统一直给他派单他全拒。筛选候选骑手放在 SQL 里做别把全表捞到内存再过滤# 候选池只取在线且有承载余量的最多 200 个进内存打分 rows conn.execute( SELECT id, cur_lng, cur_lat, load_count, updated_at FROM couriers WHERE status idle AND load_count ? ORDER BY updated_at DESC LIMIT 200, (MAX_LOAD,), ).fetchall()MAX_LOAD是单骑手承载上限同城场景常见设 5 到 8超过就不再派。LIMIT 200是一道保险防止某次数据异常把几万个骑手全捞出来打分。ORDER BY updated_at DESC让最近活跃的骑手优先进入候选池比随机截断合理。派单成功后要在同一个事务里做三件事更新shipments、更新couriers.load_count和status、写一条派单日志。这三步必须原子否则会出现骑手负载加了但履约单没建出来的脏数据。4.3 SQLite 并发写入WAL、busy_timeout 与事务边界SQLite 被诟病最多的就是并发写但绝大部分「database is locked」不是 SQLite 的问题是连接没配对。这个项目的连接工厂长这样# app/db.py import sqlite3 from contextlib import contextmanager DB_PATH delivery.db def get_conn() - sqlite3.Connection: conn sqlite3.connect(DB_PATH, timeout5.0, isolation_levelNone) conn.row_factory sqlite3.Row # 让查询结果能按列名取值 conn.execute(PRAGMA journal_mode WAL) # 读写不互斥 conn.execute(PRAGMA synchronous NORMAL) # WAL 下这个档位足够安全 conn.execute(PRAGMA busy_timeout 5000) # 锁等待 5 秒再报错 conn.execute(PRAGMA foreign_keys ON) return conn contextmanager def transaction(): 显式事务正常提交异常回滚 conn get_conn() try: conn.execute(BEGIN IMMEDIATE) # 立刻拿写锁避免升级锁时死等 yield conn conn.execute(COMMIT) except Exception: conn.execute(ROLLBACK) raise finally: conn.close()journal_mode WAL是读写并发的基石开了之后读操作不会被写操作阻塞同城派送里「骑手上报位置」和「客服查订单」可以同时进行。synchronous NORMAL在 WAL 模式下意味着崩溃可能丢最后几个事务但不会损坏数据库文件对配送场景是可接受的取舍如果业务不能接受丢单改成FULL代价是每次提交都要 fsync写入吞吐会掉一个量级。BEGIN IMMEDIATE是最容易被忽略的一行。默认的BEGIN DEFERRED是等到第一条写语句才尝试拿锁如果事务里先读后写可能在中途才发现拿不到写锁这时要处理锁升级失败逻辑很绕。IMMEDIATE一开始就拿写锁拿不到直接按busy_timeout等待行为可预测得多。isolation_levelNone是关掉 Python 的隐式事务管理让事务边界完全由代码里的BEGIN/COMMIT控制。不关的话sqlite3模块会自作主张在某些语句前开事务和你手写的BEGIN撞车报「cannot start a transaction within a transaction」。提示busy_timeout不是越大越好。设到 30 秒请求会一直挂着不返回前端以为超时重试反而把压力放大。5 秒是个比较平衡的值超过这个时间基本说明有长事务在跑该去查是谁了。4.4 轨迹落库高频写入用攒批别一条一条插骑手端一般 3 到 5 秒上报一次坐标100 个骑手在线就是每秒 20 到 30 次插入每次都单独开事务的话SQLite 的 fsync 开销会把磁盘打满。项目里的做法是内存攒批攒够条数或到时间窗口再一次性executemany# app/track_buffer.py import time, threading class TrackBuffer: def __init__(self, conn_factory, batch_size200, flush_interval1.0): self._buf [] self._lock threading.Lock() self._conn_factory conn_factory self._batch_size batch_size self._interval flush_interval def add(self, shipment_id, courier_id, lng, lat): with self._lock: self._buf.append((shipment_id, courier_id, lng, lat, int(time.time() * 1000))) if len(self._buf) self._batch_size: self._flush_locked() def _flush_locked(self): if not self._buf: return rows, self._buf self._buf, [] with self._conn_factory() as conn: conn.executemany( INSERT INTO tracks(shipment_id, courier_id, lng, lat, reported_at) VALUES (?, ?, ?, ?, ?), rows ) def flush_loop(self): 后台线程按固定间隔兜底刷盘防止低峰期数据一直压在内存 while True: time.sleep(self._interval) with self._lock: self._flush_locked()batch_size 200是权衡后的值太小起不到攒批效果太大则内存里压的数据多进程被 kill 时丢的轨迹也多。flush_interval 1.0保证低峰期即使一个骑手都没上报内存里那几条也会在一秒内落库客服查轨迹不会看到延迟。executemany在 SQLite 里会被包成单条事务执行200 条插入的 fsync 次数从 200 次降到 1 次实测写入吞吐能差一个数量级。这个方案的代价是进程异常退出会丢最后一批数据。同城派送的轨迹属于「少几个点不影响判责」的数据可以接受如果业务要求轨迹零丢失那就得改成写本地日志文件再回放复杂度会上去不少。5. 避坑与排查SQLite 在同城派送场景的五个真实坑5.1 坑一一压测就database is locked现象本地单请求跑得好好的一上 20 并发压测日志里刷屏sqlite3.OperationalError: database is locked接口大面积 500。原因两个层面的问题叠在一起。一是连接没开 WAL默认的 rollback journal 模式下写操作会独占整库二是 Pythonsqlite3的默认timeout是 5 秒但很多人建连接时只写了sqlite3.connect(path)没意识到某些框架封装里timeout被改成了 0一撞锁立刻抛异常不等待。解决统一走db.py的连接工厂确保PRAGMA journal_mode WAL、PRAGMA busy_timeout 5000、timeout5.0三处都设上。另外把长事务拆短尤其别在一个事务里做 HTTP 调用比如派单时同步调地图 API 算路线网络一慢写锁就被人攥着不放。5.2 坑二时间字段存成字符串范围查询走不了索引现象订单列表按时间倒序查前一万条还行到十万条时接口从 30ms 涨到 800msEXPLAIN QUERY PLAN显示全表扫描。原因早期建表时把created_at写成TEXT存2024-05-01 10:00:00查询时用WHERE created_at 2024-05-01做字符串比较。逻辑上能跑通但一旦表里混进不同格式有的带毫秒、有的带时区后缀索引的有序性就用不上了优化器直接放弃索引改全扫。解决时间统一存毫秒整型索引建在整型列上。已有数据用一次性迁移脚本转换UPDATE orders SET created_at CAST(strftime(%s, created_at) AS INTEGER) * 1000。转换前先备份转换后用EXPLAIN QUERY PLAN确认走了idx_ship_status。5.3 坑三两个骑手同时点「接单」同一单被派了两次现象调度后台看到一条履约单关联了两个骑手两个骑手都以为自己接了这单跑到店里撞上。原因派单逻辑是先SELECT查可派骑手再UPDATE写入中间没有原子性。两个请求几乎同时进来都查到了同一个空闲骑手都执行了更新后写的覆盖先写的但前端两个都收到了成功。这是经典的丢失更新。解决改条件更新把「骑手是否空闲」作为WHERE条件的一部分靠rowcount判断抢没抢到cur conn.execute( UPDATE couriers SET statusbusy, load_countload_count1 WHERE id? AND statusidle, (courier_id,) ) if cur.rowcount 0: # 没抢到换下一个候选骑手重试 return try_next_candidate()rowcount 0说明在你读取之后这个骑手已经被别人占了直接换下一个候选不要重试同一个。这一步必须和shipments的插入在同一个BEGIN IMMEDIATE事务里否则还是会有中间态。5.4 坑四轨迹表涨到两千万行履约详情页打不开现象上线三个月后查单个订单的轨迹列表要 3 秒以上页面直接转圈超时。原因tracks表只有主键索引查询语句是SELECT * FROM tracks WHERE shipment_id ? ORDER BY reported_at DESC。没有联合索引SQLite 只能扫全表再排序表越大越慢而且SELECT *把每行都读出来磁盘 IO 也扛不住。解决建(shipment_id, reported_at DESC)的联合索引覆盖过滤和排序两个动作一次索引扫描就能按序返回。同时把SELECT *改成只取需要的列。已经很大的表补索引用CREATE INDEX会锁库低峰期执行或者在维护窗口用「建新表 灌数据 改名」的方式做在线迁移。长期方案是按月分表把历史轨迹归档到tracks_202405这类表里主表只留最近三个月。5.5 坑五直接cp delivery.db备份恢复后数据不全现象运维同学每天定时cp delivery.db backup/某次机房迁移后恢复发现最近几小时的单全没了甚至有一次库文件直接打不开。原因开了 WAL 之后最近提交的数据还在delivery.db-wal文件里没有 checkpoint 回主库。只拷.db不拷-wal和-shm等于拷了个半成品如果在写入过程中直接cp还可能拷到事务进行中的中间状态文件级损坏。解决备份必须走 SQLite 官方提供的在线备份接口或者用VACUUM INTO# 方式一在线备份不阻塞读写得到的是完整一致快照 sqlite3 delivery.db .backup backup/delivery_$(date %Y%m%d_%H%M).db # 方式二VACUUM INTO顺带整理碎片只读操作 sqlite3 delivery.db VACUUM INTO backup/delivery_clean.db如果非要用文件拷贝先执行PRAGMA wal_checkpoint(TRUNCATE)把 WAL 刷回主库停写之后再cp三个文件.db-wal-shm一起拷。但既然有.backup命令就别折腾文件拷贝了一行命令的事。6. 二次开发从单机版走向可切换存储与多运力6.1 先抽仓储层为换库留一个口子单机版跑顺之后第一个要动的地方是存储。别等到真换 PostgreSQL 那天才发现 SQL 散落在二十个路由文件里。做法是先抽一层仓储接口把「查候选骑手」「抢骑手」「写轨迹」这些动作定义成方法路由只调方法不写 SQL# app/repo/base.py class CourierRepo: def list_available(self, max_load: int, limit: int 200): ... def try_occupy(self, courier_id: int) - bool: ... # 返回是否抢到 # app/repo/sqlite_repo.py class SqliteCourierRepo(CourierRepo): def try_occupy(self, courier_id): cur self.conn.execute( UPDATE couriers SET statusbusy, load_countload_count1 WHERE id? AND statusidle, (courier_id,) ) return cur.rowcount 1try_occupy返回布尔值而不是抛异常是为了让上层派单逻辑能自然地做「换下一个候选」的循环不用写 try/except 控制流。抽完这层把main.py里的依赖注入指向SqliteCourierRepo将来写一个PgCourierRepo改一行配置就能切不需要动业务代码。6.2 加运力属性大件、保温箱、载重上限同城派送往上做一步必然会遇到「这单是 20 公斤的水普通电动车拉不了」。改造点有两处couriers表加vehicle_typeebike / van、max_weight_kg、has_insulation三个字段派单候选池的 SQL 里加过滤条件。ALTER TABLE couriers ADD COLUMN vehicle_type TEXT NOT NULL DEFAULT ebike; ALTER TABLE couriers ADD COLUMN max_weight_kg REAL NOT NULL DEFAULT 20; ALTER TABLE couriers ADD COLUMN has_insulation INTEGER NOT NULL DEFAULT 0; -- 订单侧也要记录运力需求否则没法匹配 ALTER TABLE orders ADD COLUMN weight_kg REAL NOT NULL DEFAULT 1; ALTER TABLE orders ADD COLUMN need_insulation INTEGER NOT NULL DEFAULT 0;候选池查询改成WHERE statusidle AND load_count ? AND max_weight_kg ?保温需求再加一条AND has_insulation 1。注意 ALTER TABLE 加带默认值的非空列在 SQLite 里是支持的大表上会因为改写每一行而变慢几百万行以上建议用「建新表 灌数据 改名」的方式别在业务高峰期直接跑。6.3 验证方法先写状态机单测再压派单接口改完之后怎么确认没改坏两个层面。状态机层面写参数化单测把所有合法和非法迁移对都覆盖一遍跑得快、回归成本低。派单层面写一个简单的并发脚本起 50 个线程同时抢同一批订单断言每个订单最终只对应一个骑手、load_count总和等于成功派单数。这个断言能抓住绝大多数事务边界没写对的问题。import pytest from app.state_machine import assert_transition, InvalidTransition pytest.mark.parametrize(cur,tgt, [ (created, dispatched), (picked, delivered), (dispatched, picked), ]) def test_legal(cur, tgt): assert_transition(cur, tgt) # 不抛异常即通过 pytest.mark.parametrize(cur,tgt, [ (delivered, dispatched), (cancelled, picked), (unknown, picked), ]) def test_illegal(cur, tgt): with pytest.raises(InvalidTransition): assert_transition(cur, tgt)这套测试写下来不到一百行但每次改状态机都会帮你挡一次。我一般还会在 CI 里加一条sqlite3 delivery.db PRAGMA integrity_check;输出不是ok就直接挂掉构建。顺便说个改造顺序上的建议先抽仓储层再加字段最后动派单打分。反过来做的话你会在一堆散落的 SQL 里改字段名改到怀疑人生。派单权重这种参数最好抽到配置文件里配合一个小的 A/B 开关线上调权重的时候不用发版。从那以后我每次给这类项目做改造都强制先跑一遍状态机单测再动派单逻辑顺序一乱就得花两倍时间找回滚点。希望帮到你。本文还有配套的精品资源点击获取
