實(shí)戰(zhàn)：FastAPI+uniapp搭建撮合平臺全解析)
這兩年零工經(jīng)濟(jì)起來得特別快身邊搞裝修、跑腿、臨時搬運(yùn)、家政保潔這類需求越來越碎片化。我做了一個微信小程序端的零工市場服務(wù)系統(tǒng)技術(shù)棧選的是Python后端加uniapp跨端前端整條鏈路從需求梳理到數(shù)據(jù)庫設(shè)計(jì)、接口開發(fā)、小程序上線前后折騰了一個多月。這篇文章把這套系統(tǒng)的核心設(shè)計(jì)、技術(shù)選型邏輯和踩過的坑完整寫出來給正準(zhǔn)備做類似C2C服務(wù)撮合平臺的朋友一個可參考的樣本。先說這套系統(tǒng)能干什么雇主可以在上面發(fā)布零工需求比如“明天上午需要一個搬運(yùn)工”工人端按距離、報(bào)價、技能標(biāo)簽刷單子雙方在線溝通、確認(rèn)接單、線下完工后在平臺結(jié)算費(fèi)用系統(tǒng)里跑完“發(fā)布—接單—履約—結(jié)算—評價”這整個閉環(huán)。它解決的痛點(diǎn)很明確——零工市場供需極度分散需求方找人不方便供給方接單靠微信群碰運(yùn)氣中間缺一個結(jié)構(gòu)化、帶信用評價的交易平臺。適合誰參考呢想做本地生活服務(wù)、校園跑腿、兼職撮合、家政中介類產(chǎn)品的人以及剛?cè)腴Tuniapp加Python前后端分離開發(fā)、想完整走一遍項(xiàng)目的人。1. 項(xiàng)目整體設(shè)計(jì)與技術(shù)選型1.1 零工市場到底要解決什么問題把零工平臺拆開看它本質(zhì)上是一個雙邊交易市場。跟電商平臺不一樣零工市場賣的是一種“非標(biāo)準(zhǔn)化服務(wù)”這導(dǎo)致它在產(chǎn)品設(shè)計(jì)上有幾個特殊矛盾。第一個矛盾是供需不匹配的結(jié)構(gòu)性差異。需求方要的是“解決某件事”工人提供的是“某段時間的勞動力”。所以商品零工單不能像實(shí)物商品那樣標(biāo)準(zhǔn)化描述必須有詳細(xì)的內(nèi)容字段比如工作地點(diǎn)、預(yù)估耗時、技能要求、結(jié)算方式甚至“工具由誰提供”這種細(xì)節(jié)。我在設(shè)計(jì)發(fā)布表單的時候字段定得細(xì)后面匹配和糾紛處理才省事。第二個矛盾是信任問題比商品交易更嚴(yán)重。實(shí)物商品有運(yùn)費(fèi)險、七天無理由零工服務(wù)簽不了合同、退不了貨。解決的思路就是引入雙向評價、實(shí)名認(rèn)證(對接微信手機(jī)號能力)、保證金/定金機(jī)制。這套系統(tǒng)里我做了“雇主托管費(fèi)用、工人完成后打款”的中間賬戶模式而不是直接線下轉(zhuǎn)賬。第三個矛盾是訂單狀態(tài)比普通電商復(fù)雜。零工訂單不是下單就完了要經(jīng)歷“發(fā)布—報(bào)名—確認(rèn)—開工—完工—驗(yàn)收—結(jié)算—評價”多個階段而且每個階段都可能被取消。狀態(tài)機(jī)設(shè)計(jì)是這套系統(tǒng)里最核心的部分后面會展開講。1.2 為什么前端選uniapp而不是原生小程序很多人糾結(jié)這個問題。我當(dāng)時選uniapp的核心理由是一套代碼、多端復(fù)用。零工市場這種業(yè)務(wù)天然適合微信小程序獲客但后期很可能要做支付寶小程序、抖音小程序甚至獨(dú)立App因?yàn)楣と巳后w對App有使用慣性。如果前端用原生微信小程序開發(fā)后面每加一個端就是重寫一遍成本翻倍。uniapp的具體優(yōu)勢我用下來有三點(diǎn)比較實(shí)在。第一是語法成本低。它基于Vue語法會Vue的同事上手幾乎零成本組件化開發(fā)在多人協(xié)作時很舒服。第二是周邊生態(tài)可用。零工市場要發(fā)定位、選地圖uniapp里可以直接封裝騰訊地圖或高德地圖不需要自己寫原生插件。第三是條件編譯能力。#ifdef MP-WEIXIN這種寫法可以針對不同平臺做差異化處理比如微信小程序里用wx.login獲取codeApp端就用自己的登錄SDK一套代碼里寫兩套邏輯也不亂。當(dāng)然uniapp也有坑。最大的坑是性能上限不如原生尤其是長列表渲染和復(fù)雜動畫我在零工列表頁用了virtual-list虛擬列表組件來規(guī)避這個問題。另一個坑是第三方SDK兼容性比如微信支付雖然uniapp封裝了uni.requestPayment但不同端的喚起參數(shù)格式有差異這塊必須寫平臺適配代碼不能圖省事一把梭。1.3 Python后端框架怎么選Python后端可選的框架很多Flask、Django、FastAPI。我做這個項(xiàng)目選的是FastAPI理由也直接。性能FastAPI基于ASGI異步框架并發(fā)能力比Flask的WSGI模式強(qiáng)不少。零工市場高峰期往往集中在上午和晚飯后用戶瞬間刷單量比較大異步IO能扛住。自動生成接口文檔FastAPI內(nèi)置Swagger文檔寫完接口就能在瀏覽器里調(diào)試前后端聯(lián)調(diào)效率高很多。對于一人開發(fā)的個人項(xiàng)目來說這功能太省事了。類型校驗(yàn)Pydantic做的請求參數(shù)校驗(yàn)寫清楚類型注解前端傳錯參數(shù)馬上能看出來問題。生態(tài)兼容SQLAlchemy 2.0的異步版本跟FastAPI配合得很好數(shù)據(jù)庫操作不阻塞事件循環(huán)。要說缺點(diǎn)FastAPI的小眾程度確實(shí)不如Flask遇到問題網(wǎng)上搜到的資料少一些。但官方文檔寫得很清楚上手成本并不高。我用它寫這個項(xiàng)目整體體驗(yàn)比用Django輕量比用Flask舒服。1.4 整體技術(shù)架構(gòu)與模塊劃分這個系統(tǒng)的完整技術(shù)鏈路是這樣小程序/App端uniapp Vue3 ↓ HTTPS/JSON 后端APIFastAPI Uvicorn ↓ SQLAlchemy ORM MySQL 8.0業(yè)務(wù)數(shù)據(jù) ↓ Redis緩存、驗(yàn)證碼、分布式鎖 ↓ 對象存儲OSS用戶頭像、零工圖片、憑證業(yè)務(wù)模塊劃分我一開始就定了七個用戶模塊微信登錄、手機(jī)號綁定、身份切換雇主/工人、資質(zhì)信息零工模塊發(fā)布需求、需求大廳列表、條件篩選、關(guān)鍵詞搜索訂單模塊報(bào)名/接單、雇主確認(rèn)、訂單狀態(tài)流轉(zhuǎn)、取消與異常處理結(jié)算模塊微信支付V3、資金托管、完工打款、退款評價模塊雙向評價、信用分消息模塊系統(tǒng)通知、接單提醒主要是訂閱消息管理后臺審核零工單、處理糾紛、用戶管理模塊之間通過訂單狀態(tài)這個“總線”串起來這也是我拆解整個系統(tǒng)時最花心思的地方。2. 數(shù)據(jù)庫設(shè)計(jì)先把業(yè)務(wù)變成表2.1 核心表結(jié)構(gòu)拆解數(shù)據(jù)庫是業(yè)務(wù)的底座表設(shè)計(jì)得好不好直接決定后期開發(fā)爽不爽。我前后改了三個版本最后定下來的核心表有這些。用戶表userid、openid微信唯一標(biāo)識、unionid、nickname、avatar、phone、role1-雇主、2-工人、3-雙身份、credit_score、status1-正常、2-封禁。這里要說明的是微信小程序登錄時用wx.login拿的是code用來換openid但用戶手機(jī)號需要單獨(dú)點(diǎn)擊授權(quán)按鈕才能拿到所以phone字段是后期補(bǔ)充的。零工表gig_orderid、user_id發(fā)布者ID、title標(biāo)題、description描述、category工種分類、province/city/district地區(qū)、address詳細(xì)地址、longitude/latitude經(jīng)緯度、budget_low/budget_high預(yù)算區(qū)間、start_time/end_time預(yù)計(jì)工作時段、need_count需要人數(shù)、skill_tag技能要求、status1-招聘中、2-已滿、3-已完成、4-已取消、view_count瀏覽量。報(bào)名/接單表gig_applyid、gig_order_id、user_id申請人、price報(bào)價金額、message自我介紹、status1-待確認(rèn)、2-已接受、3-已拒絕、4-已完成、created_at。交易表transactionid、gig_order_id、employer_id、worker_id、amount、pay_status1-待支付、2-已托管、3-已打款、4-已退款、pay_time、settle_time。評價表reviewid、gig_order_id、from_user_id、to_user_id、rating1-5分、content、created_at。這里有一個容易踩的坑零工單和訂單要不要拆成兩張表我的做法是拆開的。零工表是“需求信息”報(bào)名表里被雇主確認(rèn)的那個申請記錄才升級成“訂單”。為什么要拆因?yàn)橐粋€零工單可以被多個工人報(bào)名但最終可能只需要一個人。如果直接在零工表里存“誰接單”就存不下多個人報(bào)名的記錄后面做提名、候補(bǔ)、取消接單就很被動。拆成兩張表之后gig_apply表的status已接受那條記錄就相當(dāng)于“臨時履約合同”。2.2 訂單狀態(tài)機(jī)設(shè)計(jì)別讓業(yè)務(wù)亂成一鍋粥這塊是系統(tǒng)最核心的地方。零工訂單的狀態(tài)流轉(zhuǎn)我用狀態(tài)機(jī)精確控制后端接收每一次狀態(tài)變更時先校驗(yàn)“當(dāng)前狀態(tài) 操作事件”是否合法不合法直接拒絕。標(biāo)準(zhǔn)流轉(zhuǎn)路徑招聘中 → 報(bào)名 → 雇主確認(rèn) → 已接單 → 工人開工 → 驗(yàn)收完成 → 已結(jié)算 → 已評價允許的跳轉(zhuǎn)招聘中 → 已取消雇主主動撤銷且報(bào)名人數(shù)為0已接單 → 已取消雙方協(xié)商或超時未開工雇主可取消已接單 → 驗(yàn)收完成工人提交完工雇主確認(rèn)驗(yàn)收完成 → 已結(jié)算結(jié)算模塊打款成功后更新狀態(tài)我在代碼里實(shí)現(xiàn)時用的是一個TransitionDict# 狀態(tài)機(jī)定義 STATE_TRANSITIONS { recruiting: {apply, cancel}, assigned: {start, cancel, complete}, completed: {settle}, settled: {review}, }狀態(tài)機(jī)的好處是后端代碼里到處是if gig.status xxx這種判斷根本沒法維護(hù)狀態(tài)機(jī)把規(guī)則收斂到一個地方邏輯清晰出bug的概率也小。2.3 結(jié)算與錢包邏輯零工市場做結(jié)算最忌諱的是“平臺先收款再打款”的模式被用戶誤解為資金池。我的設(shè)計(jì)里引入了**交易單transaction**這種表結(jié)構(gòu)把平臺的賬目邏輯獨(dú)立出來。交易流程是雇主確認(rèn)工人后先調(diào)微信支付V3托管這筆錢狀態(tài)已托管→ 工人完工、雇主確認(rèn)驗(yàn)收后平臺觸發(fā)結(jié)算狀態(tài)已打款。這里特別注意打款人不是平臺自己而是通過微信支付的商家轉(zhuǎn)賬接口把托管的款項(xiàng)轉(zhuǎn)給工人。整個鏈路中平臺不碰資金只是傳遞微信支付的結(jié)果。資金安全上還要加一道“對賬”。每天跑一個定時任務(wù)把微信支付賬單和本地transaction表對比金額不一致就告警。這個功能是小程序上線后必須做的否則資金差錯根本發(fā)現(xiàn)不了。3. 后端API設(shè)計(jì)與核心接口實(shí)現(xiàn)3.1 用FastAPI搭建項(xiàng)目骨架后端項(xiàng)目我按模塊拆成這樣的目錄結(jié)構(gòu)app/ ├── main.py # 應(yīng)用入口、路由注冊 ├── config.py # 配置項(xiàng)數(shù)據(jù)庫、Redis、微信參數(shù) ├── models/ # SQLAlchemy ORM模型 ├── schemas/ # Pydantic請求/響應(yīng)模型 ├── api/ # 路由模塊 │ ├── user.py │ ├── gig.py │ ├── order.py │ ├── pay.py │ └── review.py ├── services/ # 業(yè)務(wù)邏輯層 ├── core/ # 安全、依賴注入、微信SDK封裝 └── tests/ # 單元測試入口文件不復(fù)雜關(guān)鍵是把中間件、CORS、路由掛載好from fastapi import FastAPI from fastapi.middleware.cors import CORSMiddleware from app.api import user, gig, order, pay, review app FastAPI(title零工市場服務(wù)系統(tǒng), version1.0.0) app.add_middleware( CORSMiddleware, allow_origins[*], allow_methods[*], allow_headers[*], ) app.include_router(user.router, prefix/api/user, tags[用戶]) app.include_router(gig.router, prefix/api/gig, tags[零工]) app.include_router(order.router, prefix/api/order, tags[訂單]) app.include_router(pay.router, prefix/api/pay, tags[支付]) app.include_router(review.router, prefix/api/review, tags[評價]) app.get(/health) def health_check(): return {status: ok}3.2 零工發(fā)布與列表接口發(fā)布零工接口是寫操作里最核心的我做了比較嚴(yán)格的參數(shù)校驗(yàn)。注意Pydantic模型里budget_low和budget_high要校驗(yàn)大小關(guān)系start_time要在當(dāng)前時間之后。class GigCreate(BaseModel): title: str Field(..., min_length4, max_length50) description: str Field(, max_length500) category: str city: str district: str address: str longitude: float latitude: float budget_low: Decimal budget_high: Decimal start_time: datetime end_time: datetime need_count: int Field(1, ge1, le10) skill_tag: str model_validator(modeafter) def check_budget(self): if self.budget_high self.budget_low: raise ValueError(預(yù)算上限不能低于下限) if self.end_time self.start_time: raise ValueError(結(jié)束時間必須晚于開始時間) return self列表接口做的是“綜合排序 篩選”。用戶在大廳里默認(rèn)看到的是離我最近、預(yù)算合適、快要開工的單子排前面。SQL的排序邏輯用權(quán)重計(jì)算SELECT * FROM gig_order WHERE status 1 AND city 上海市 AND category IN (搬家, 搬運(yùn)) AND start_time NOW() ORDER BY (budget_high - budget_low) DESC, start_time ASC LIMIT 20 OFFSET 0實(shí)際實(shí)現(xiàn)時我用了SQLAlchemy的動態(tài)查詢構(gòu)造器前端每次傳不同的篩選條件后端動態(tài)拼SQL。這里有個經(jīng)驗(yàn)篩選條件能傳參數(shù)就用參數(shù)不確定就做成索引字段比如category、city、status三個字段一定要建聯(lián)合索引不然數(shù)據(jù)量上來后這個接口必掛。3.3 接單與訂單鎖定并發(fā)是重災(zāi)區(qū)零工接單跟電商搶購很像尤其在熱門的好單子上可能同時有幾十個人報(bào)名。報(bào)名動作本身并發(fā)量不大真正危險的是“雇主確認(rèn)工人”那一刻——同一個零工單如果被兩個雇主操作不太可能但為了防止臟讀或者同一個工人被兩個人同時確認(rèn)就會產(chǎn)生超賣。我用了Redis分布式鎖來防并發(fā)import redis.asyncio as aioredis redis_client aioredis.from_url(redis://localhost:6379/0) async def confirm_worker(gig_id: int, worker_id: int): lock_key fgig_confirm:{gig_id} # 加鎖5秒超時 acquired await redis_client.set(lock_key, 1, nxTrue, ex5) if not acquired: raise HTTPException(status_code409, detail操作太頻繁請稍后重試) try: # 檢查零工單狀態(tài)是否還是“招聘中” gig await get_gig(gig_id) if gig.status ! recruiting: raise HTTPException(status_code400, detail該零工已滿或已關(guān)閉) # 更新報(bào)名表狀態(tài) # 更新零工狀態(tài)為“已接單” ... finally: await redis_client.delete(lock_key)這種鎖的方案能擋住絕大多數(shù)并發(fā)問題。更保險的方案是用MySQL的行鎖SELECT ... FOR UPDATE但我會優(yōu)先用Redis鎖因?yàn)橹辉诖_認(rèn)這個動作上做短鎖數(shù)據(jù)庫壓力小。3.4 微信登錄與JWT鑒權(quán)微信小程序的登錄流程是固定套路前端wx.login()拿code→ 傳給后端 → 后端用code換openidsession_key→ 返回自定義登錄態(tài)。這里我再套一層JWT用戶每次請求帶上Token后端通過依賴注入拿到當(dāng)前用戶ID。app.post(/api/user/login) async def login(request: LoginRequest): # 1. 獲取openid url https://api.weixin.qq.com/sns/jscode2session params { appid: WECHAT_APPID, secret: WECHAT_SECRET, js_code: request.code, grant_type: authorization_code, } async with httpx.AsyncClient() as client: resp await client.get(url, paramsparams) data resp.json() if errcode in data: raise HTTPException(status_code400, detail微信登錄失敗) openid data[openid] # 2. 查或建用戶 user await get_user_by_openid(openid) if not user: user await create_user(openid) # 3. 生成JWT token jwt.encode({uid: user.id, exp: time.time() 7 * 24 * 3600}, SECRET_KEY, algorithmHS256) return {token: token, user_info: user} # 全局依賴獲取當(dāng)前用戶 async def get_current_user(token: str Depends(oauth2_scheme)): try: payload jwt.decode(token, SECRET_KEY, algorithms[HS256]) uid payload.get(uid) except Exception: raise HTTPException(status_code401, detail登錄已過期) user await get_user_by_id(uid) if not user: raise HTTPException(status_code401, detail用戶不存在) return user這套東西不算難但有一個點(diǎn)要注意JWT的secret必須跟業(yè)務(wù)配置分開從環(huán)境變量讀取不要硬編碼在代碼倉庫里。另一個點(diǎn)是openid不能直接當(dāng)用戶ID用因?yàn)橛脩粼谛〕绦蚶锴袚Q手機(jī)號或者換綁openid會變所以要在用戶表里單獨(dú)建自增ID作為主鍵。4. 前端核心功能實(shí)現(xiàn)4.1 頁面結(jié)構(gòu)規(guī)劃前端用uniapp Vue3 Pinia頁面結(jié)構(gòu)不復(fù)雜但tabBar的設(shè)計(jì)比較講究。零工市場有兩個核心角色我用了“身份切換”的思路而不是給雇主和工人各做一套獨(dú)立App。tabBar三個頁簽首頁零工大廳默認(rèn)是“找零工”模式顯示零工列表發(fā)布中間一個大按鈕點(diǎn)擊后先讓用戶選擇身份若是雇主角色則進(jìn)入發(fā)布表單若沒有雇主身份引導(dǎo)切換我的個人信息、我的發(fā)布、我的接單、錢包、設(shè)置這個設(shè)計(jì)的好處是用戶不需要重新下載或切換小程序一個App里完成雇主和工人的雙角色切換。代碼層面用Pinia里的userStore.role控制頁面展示。4.2 列表頁與下拉刷新、觸底加載零工大廳是流量最大的頁面做不好用戶體驗(yàn)全毀。我用的方案是首次進(jìn)入加載20條滑動到底部自動加載下一頁頂部下拉刷新。注意uniapp中H5端可以通過onReachBottom鉤子實(shí)現(xiàn)觸底加載小程序端同樣支持這塊API是統(tǒng)一的。結(jié)構(gòu)大致如下template view classgig-list view v-foritem in gigList :keyitem.id classgig-card clickgoDetail(item.id) view classgig-title{{ item.title }}/view view classgig-meta text{{ item.category }}/text text{{ item.city }}{{ item.district }}/text text{{ item.start_time }}/text /view view classgig-budget text￥{{ item.budget_low }}-{{ item.budget_high }}/text /view /view view v-ifloading classloading加載中.../view /view /template這里有一個經(jīng)驗(yàn)圖片懶加載要開。零工卡片如果有圖片直接用uniapp的image lazy-load組件否則列表滾動的時候會明顯卡頓。另外列表數(shù)據(jù)量大了以后建議用z-paging這種現(xiàn)成的分頁組件幫我處理空數(shù)據(jù)、錯誤、加載狀態(tài)省很多事。4.3 發(fā)布頁與地圖定位發(fā)布零工時用戶需要選地址和標(biāo)記定位。這塊我用uniapp內(nèi)置的uni.chooseLocation它可以拉起微信內(nèi)置地圖選擇器。但有幾個坑要提前規(guī)避uni.chooseLocation在小程序端必須配置permission里的scope.userLocation否則第一次調(diào)用會直接fail。經(jīng)緯度和地址名是兩個字段不能只存地址名否則列表頁做距離排序就沒數(shù)據(jù)可用。發(fā)布表單里工作地址支持input手填和坐標(biāo)選擇兩種方式手填地址如果沒選坐標(biāo)后端要能夠容忍經(jīng)緯度為空的場景但排序時這些單子排到最后。我之前踩過一個坑真機(jī)調(diào)試時uni.chooseLocation返回的經(jīng)緯度是gcj02坐標(biāo)系的如果直接傳給后端存庫再交給騰訊地圖SDK做逆地理編碼坐標(biāo)會有偏差。這里要統(tǒng)一坐標(biāo)系建議地圖組件、后端存儲、逆地理編碼都用gcj02坐標(biāo)系別跟GPS原始坐標(biāo)混用。4.4 用戶身份切換與個人中心身份切換在“我的”頁面里做。用戶一開始是游客登錄后默認(rèn)身份是“工人”。要發(fā)零工單需要切換到“雇主”身份第一次切換時彈窗讓他補(bǔ)全雇主信息比如真實(shí)姓名、聯(lián)系電話。個人中心要展示的信息分兩大塊作為雇主我發(fā)布的零工單列表 每個單的報(bào)名人員作為工人我報(bào)名的零工單列表 接單記錄我用Tab切換實(shí)現(xiàn)這兩種視圖列表請求不同接口。切換身份時后端要做校驗(yàn)如果當(dāng)前用戶有進(jìn)行中的零工單作為雇主未取消、作為工人報(bào)名未完成不允許切換身份否則會導(dǎo)致訂單列表混亂。5. 微信支付V3對接實(shí)戰(zhàn)5.1 對接前準(zhǔn)備微信支付V3是現(xiàn)在小程序支付的主流方案相比V2V3的密鑰體系更安全API采用RSA簽名。先說對接前的準(zhǔn)備清單微信小程序賬號個人主體不行必須是企業(yè)/個體工商戶微信支付商戶號需要企業(yè)資質(zhì)商戶API私鑰在商戶平臺生成要妥善保管APIv3密鑰商戶平臺設(shè)置用于回調(diào)報(bào)文解密微信支付平臺證書用于驗(yàn)證微信回調(diào)簽名密鑰這塊必須強(qiáng)調(diào)一點(diǎn)私鑰不要上傳到代碼倉庫更不要hardcode在前端。正確的做法是放在后端服務(wù)器環(huán)境變量或KMS密鑰管理服務(wù)里。uniapp端喚起支付用的是uni.requestPayment它需要后端返回paySign等一系列參數(shù)。流程是用戶點(diǎn)擊“確認(rèn)接單”后前端把gig_order_id傳給后端 → 后端調(diào)微信支付統(tǒng)一下單接口 → 拿到prepay_id后端用預(yù)支付ID生成paySign→ 返回給前端前端調(diào)起支付面板。5.2 統(tǒng)一下單與回調(diào)解密我在后端封裝了一個支付service核心邏輯是把下單、簽名、回調(diào)、解密各拆成一個函數(shù)。統(tǒng)一下單的關(guān)鍵參數(shù)如下# 微信支付V3統(tǒng)一下單核心參數(shù) payload { appid: WECHAT_APPID, # 小程序appid mchid: MCH_ID, # 商戶號 description: f零工單付款-{gig_id}, out_trade_no: trade_no, # 業(yè)務(wù)訂單號全局唯一 notify_url: https://api.xxx.com/api/pay/notify, amount: { total: int(amount * 100), # 單位是分一定要乘100 currency: CNY }, payer: {openid: user_openid}, # 用戶openid }這里特容易犯一個錯金額單位搞錯。微信支付V3的total字段單位是“分”不是“元”。我用Decimal類型在數(shù)據(jù)庫里存金額元到調(diào)用支付接口時再轉(zhuǎn)成整數(shù)分避免浮點(diǎn)誤差。支付回調(diào)處理是整套支付鏈路里最不能出錯的地方。微信服務(wù)器會把支付結(jié)果以POST方式推送到我們配置的notify_url這個接口必須做好兩件事一是驗(yàn)簽二是解密資源數(shù)據(jù)。app.post(/api/pay/notify) async def wechat_pay_notify(request: Request): headers request.headers body await request.body() # 1. 驗(yàn)簽用微信平臺證書驗(yàn)證請求頭里的Wechatpay-Signature verify_wechat_signature(headers, body) # 2. 解析body得到resource對象 resource json.loads(body)[resource] # 3. 解密resource.ciphertext得到訂單數(shù)據(jù) plaintext decrypt_resource(resource) data json.loads(plaintext) # 4. 修改交易單狀態(tài) await handle_pay_success(data[out_trade_no], data[transaction_id]) # 5. 返回給微信“成功”響應(yīng) return {code: SUCCESS, message: 成功}回調(diào)處理接口是冪等的微信可能因?yàn)榫W(wǎng)絡(luò)問題重復(fù)推送回調(diào)所以handle_pay_success里一定要做“如果已經(jīng)處理過就直接返回成功”的判斷不然后端會重復(fù)給工人打款。5.3 退款與時延處理用戶取消訂單、雇主取消訂單都可能涉及退款。退款走微信支付V3的退款接口金額不能超過原支付金額且必須注明退款原因。退款接口是異步的微信會返回refund_status: PROCESSING最終結(jié)果通過回調(diào)通知。所以退款狀態(tài)也要在數(shù)據(jù)庫里實(shí)時記錄PROCESSING→SUCCESS/ABNORMAL。我在管理后臺做了一張退款記錄表方便財(cái)務(wù)對賬。這里有一個運(yùn)營層面的坑不要直接對還沒支付成功的單子發(fā)起退款。比如用戶在支付面板里點(diǎn)了支付但沒完成支付就退出了此時交易單狀態(tài)是“待支付”前端不要誘導(dǎo)用戶走退款直接重新發(fā)起支付就行。只有狀態(tài)為“已托管”的訂單在取消時才走退款流程。5.4 支付對接常見異常做支付對接這段時間我整理了三個高頻異常都是真實(shí)踩過的“商戶號未配置該產(chǎn)品權(quán)限”原因是簽約的產(chǎn)品權(quán)限還沒生效或者小程序appid沒有綁定商戶號。在商戶平臺的“產(chǎn)品中心”里確認(rèn)已開通JSAPI支付并且小程序appid和商戶號是關(guān)聯(lián)狀態(tài)?！案犊畲a無效”或“用戶未授權(quán)”前端調(diào)uni.requestPayment時多半是后端返回的timeStamp、nonceStr、package參數(shù)格式不對。特別注意package字段的值是prepay_idxxx前面必須帶prepay_id前綴不能只傳ID。支付回調(diào)收不到檢查notify_url是否公網(wǎng)可訪問域名必須備案且是小程序后臺配置的合法域名。本地開發(fā)時我用了natapp做內(nèi)網(wǎng)穿透來測試回調(diào)但上線前一定要換成正式的HTTPS域名。還有一個最重要的提醒小程序的支付能力跟小程序的類目和資質(zhì)強(qiáng)綁定。零工市場屬于“居民服務(wù)/生活服務(wù)”類目需要提供營業(yè)執(zhí)照等資質(zhì)。如果小程序因?yàn)槠渌虮幌拗浦Ц侗热珙惸坎粚?、主體資質(zhì)未過審所有支付接口都會報(bào)錯所以支付功能務(wù)必在上線前就打磨好不要等到發(fā)布后發(fā)現(xiàn)用戶沒法付款。6. 打包發(fā)布與常見問題排查6.1 uniapp打包微信小程序流程uniapp打包小程序不算難但流程中有幾個容易忽略的環(huán)節(jié)。按照這個步驟來基本不會翻車在HBuilderX里選擇“運(yùn)行到小程序模擬器”還是“發(fā)行到微信小程序”平時開發(fā)用運(yùn)行模式發(fā)布用發(fā)行模式。發(fā)行前檢查manifest.json里的小程序appid是否正確這個appid必須是注冊好的小程序appid不能是測試號。在微信公眾平臺里配置request合法域名和uploadFile合法域名后端接口域名必須在這里白名單否則小程序里網(wǎng)絡(luò)請求全部被攔截。用HBuilderX發(fā)行后生成dist/build/mp-weixin目錄然后用微信開發(fā)者工具導(dǎo)入這個目錄提交審核。審核周期一般1-7天個人主體的話類目審核可能更嚴(yán)。零工市場這個類目建議申請時選“生活服務(wù) 其他生活服務(wù)”然后準(zhǔn)備軟件著作權(quán)證書。我第一次提審的時候被拒了兩次原因都是“類目與資質(zhì)不符”后來上傳了軟件著作權(quán)材料并且把“接單”頁的交互邏輯做完整才過審。6.2 真機(jī)調(diào)試與打包常見報(bào)錯真機(jī)調(diào)試連不上確保手機(jī)和電腦在同一局域網(wǎng)微信開發(fā)者工具選擇了“真機(jī)調(diào)試”并且小程序后臺把開發(fā)者本人的微信號加為體驗(yàn)成員。打包后請求全部404大概率是環(huán)境變量問題。我在config.js里同時寫了devBaseUrl和prodBaseUrl打包時用環(huán)境變量切到正式域名。樣式錯亂uniapp的rpx單位在小屏上比較正常但某些安卓機(jī)的WebView渲染有差異。我的處理辦法是所有多行文本統(tǒng)一用text-overflow: ellipsis加-webkit-line-clamp做截?cái)啾苊饪ㄆ叨炔灰恢乱疱e位。iOS上輸入框被軟鍵盤頂上去這是uniapp老坑尤其是評論區(qū)或發(fā)布頁的textarea在iOS Safari上會被軟鍵盤頂飛。解決方法是設(shè)置adjust-positionfalse自己監(jiān)聽軟鍵盤彈起高度來調(diào)整輸入框位置我封裝了一個keyboard-height的mixins來解決。6.3 分享被覆蓋與自定義分享實(shí)現(xiàn)微信小程序的分享功能如果不做任何處理默認(rèn)是分享整個頁面。但在零工市場里用戶更希望分享“某個零工單詳情頁”給朋友或微信群。我用onShareAppMessage實(shí)現(xiàn)自定義分享內(nèi)容但遇到一個坑小程序內(nèi)部定義了全局的分享方法各頁面如果沒有單獨(dú)覆蓋就會走全局邏輯。我的做法是在每個需要分享的頁面重寫onShareAppMessage并且加一個shareTicket判斷支持群分享后通過wx.getShareInfo獲取群ID這樣方便后端做“群派單”場景的統(tǒng)計(jì)分析。// 零工詳情頁 onShareAppMessage() { const gigId this.gigId; return { title: 零工${this.gigTitle}, path: /pages/gig/detail?id${gigId}, imageUrl: this.gigCover, }; }這里提醒一個細(xì)節(jié)path里的參數(shù)必須是query形式不能是params形式否則分享點(diǎn)進(jìn)來后onLoad里取不到參數(shù)。6.4 上線前的自檢清單項(xiàng)目要真正上線我列了一個自檢清單貼出來供大家對照微信支付回調(diào)路徑為公網(wǎng)HTTPS域名且證書有效后端接口全部走HTTPS且只暴露最小化端口數(shù)據(jù)庫啟動自動備份每天凌晨全量備份一次用戶敏感信息手機(jī)號、姓名在數(shù)據(jù)庫加密存儲敏感接口修改余額、提現(xiàn)做了操作日志和審計(jì)前端所有圖片都開啟了懶加載列表接口做了分頁限流后臺管理端只能通過白名單IP訪問零工單審核機(jī)制已上線防止虛假招聘信息以上任何一條出問題都可能導(dǎo)致小程序?qū)徍耸』蛘哂脩敉对V。尤其第二條現(xiàn)在微信對數(shù)據(jù)安全的審查越來越嚴(yán)不符合要求會直接讓小程序下架。7. 零工市場系統(tǒng)的后續(xù)擴(kuò)展方向最后聊一點(diǎn)我對這套系統(tǒng)后續(xù)演進(jìn)的想法。首版跑通之后零工市場服務(wù)系統(tǒng)還可以往這幾個方向擴(kuò)展。第一個方向是智能匹配。目前前端還停留在列表刷單的模式下一步可以基于用戶的技能標(biāo)簽、歷史接單數(shù)據(jù)、當(dāng)前定位用推薦算法把“工人可能感興趣的零工單”推到首頁。這不需要多復(fù)雜的模型先做基于標(biāo)簽的召回再按距離排序體驗(yàn)就會好不少。第二個方向是信用體系升級。目前評價系統(tǒng)還算基礎(chǔ)后續(xù)可以引入行為信譽(yù)分比如“無責(zé)取消扣分”“按時到崗加分”分?jǐn)?shù)高的工人在列表里優(yōu)先展示雇主評分低的用戶發(fā)布零工時需要上傳押金。這個機(jī)制能極大減少交易糾紛。第三個方向是企業(yè)級服務(wù)接口。零工市場的單體小程序做到一定規(guī)模可以開放給勞務(wù)公司、商家讓他們通過API批量發(fā)布用工需求平臺按撮合成功抽傭。這種企業(yè)端的接口設(shè)計(jì)需要和C端做權(quán)限隔離技術(shù)上可以基于OAuth2.0做授權(quán)。從需求分析到數(shù)據(jù)庫設(shè)計(jì)再到前后端聯(lián)調(diào)、支付對接、上線審核這套零工市場系統(tǒng)走完了一個完整的產(chǎn)品生命周期。整個過程中我最大的體會是這類撮合平臺的技術(shù)難點(diǎn)不在某個單點(diǎn)功能而在狀態(tài)管理和資金安全這兩條主線上。狀態(tài)機(jī)設(shè)計(jì)得清楚前后端聯(lián)調(diào)效率翻倍支付流程每一步都嚴(yán)謹(jǐn)上線后才敢安心睡覺。希望這篇文章能給正在做類似項(xiàng)目的人一些參考少走幾步彎路。 零工市場小程序開發(fā)實(shí)戰(zhàn)：FastAPI+uniapp搭建撮合平臺全解析
這兩年零工經(jīng)濟(jì)起來得特別快身邊搞裝修、跑腿、臨時搬運(yùn)、家政保潔這類需求越來越碎片化。我做了一個微信小程序端的零工市場服務(wù)系統(tǒng)技術(shù)棧選的是Python后端加uniapp跨端前端整條鏈路從需求梳理到數(shù)據(jù)庫設(shè)計(jì)、接口開發(fā)、小程序上線前后折騰了一個多月。這篇文章把這套系統(tǒng)的核心設(shè)計(jì)、技術(shù)選型邏輯和踩過的坑完整寫出來給正準(zhǔn)備做類似C2C服務(wù)撮合平臺的朋友一個可參考的樣本。先說這套系統(tǒng)能干什么雇主可以在上面發(fā)布零工需求比如“明天上午需要一個搬運(yùn)工”工人端按距離、報(bào)價、技能標(biāo)簽刷單子雙方在線溝通、確認(rèn)接單、線下完工后在平臺結(jié)算費(fèi)用系統(tǒng)里跑完“發(fā)布—接單—履約—結(jié)算—評價”這整個閉環(huán)。它解決的痛點(diǎn)很明確——零工市場供需極度分散需求方找人不方便供給方接單靠微信群碰運(yùn)氣中間缺一個結(jié)構(gòu)化、帶信用評價的交易平臺。適合誰參考呢想做本地生活服務(wù)、校園跑腿、兼職撮合、家政中介類產(chǎn)品的人以及剛?cè)腴Tuniapp加Python前后端分離開發(fā)、想完整走一遍項(xiàng)目的人。1. 項(xiàng)目整體設(shè)計(jì)與技術(shù)選型1.1 零工市場到底要解決什么問題把零工平臺拆開看它本質(zhì)上是一個雙邊交易市場。跟電商平臺不一樣零工市場賣的是一種“非標(biāo)準(zhǔn)化服務(wù)”這導(dǎo)致它在產(chǎn)品設(shè)計(jì)上有幾個特殊矛盾。第一個矛盾是供需不匹配的結(jié)構(gòu)性差異。需求方要的是“解決某件事”工人提供的是“某段時間的勞動力”。所以商品零工單不能像實(shí)物商品那樣標(biāo)準(zhǔn)化描述必須有詳細(xì)的內(nèi)容字段比如工作地點(diǎn)、預(yù)估耗時、技能要求、結(jié)算方式甚至“工具由誰提供”這種細(xì)節(jié)。我在設(shè)計(jì)發(fā)布表單的時候字段定得細(xì)后面匹配和糾紛處理才省事。第二個矛盾是信任問題比商品交易更嚴(yán)重。實(shí)物商品有運(yùn)費(fèi)險、七天無理由零工服務(wù)簽不了合同、退不了貨。解決的思路就是引入雙向評價、實(shí)名認(rèn)證(對接微信手機(jī)號能力)、保證金/定金機(jī)制。這套系統(tǒng)里我做了“雇主托管費(fèi)用、工人完成后打款”的中間賬戶模式而不是直接線下轉(zhuǎn)賬。第三個矛盾是訂單狀態(tài)比普通電商復(fù)雜。零工訂單不是下單就完了要經(jīng)歷“發(fā)布—報(bào)名—確認(rèn)—開工—完工—驗(yàn)收—結(jié)算—評價”多個階段而且每個階段都可能被取消。狀態(tài)機(jī)設(shè)計(jì)是這套系統(tǒng)里最核心的部分后面會展開講。1.2 為什么前端選uniapp而不是原生小程序很多人糾結(jié)這個問題。我當(dāng)時選uniapp的核心理由是一套代碼、多端復(fù)用。零工市場這種業(yè)務(wù)天然適合微信小程序獲客但后期很可能要做支付寶小程序、抖音小程序甚至獨(dú)立App因?yàn)楣と巳后w對App有使用慣性。如果前端用原生微信小程序開發(fā)后面每加一個端就是重寫一遍成本翻倍。uniapp的具體優(yōu)勢我用下來有三點(diǎn)比較實(shí)在。第一是語法成本低。它基于Vue語法會Vue的同事上手幾乎零成本組件化開發(fā)在多人協(xié)作時很舒服。第二是周邊生態(tài)可用。零工市場要發(fā)定位、選地圖uniapp里可以直接封裝騰訊地圖或高德地圖不需要自己寫原生插件。第三是條件編譯能力。#ifdef MP-WEIXIN這種寫法可以針對不同平臺做差異化處理比如微信小程序里用wx.login獲取codeApp端就用自己的登錄SDK一套代碼里寫兩套邏輯也不亂。當(dāng)然uniapp也有坑。最大的坑是性能上限不如原生尤其是長列表渲染和復(fù)雜動畫我在零工列表頁用了virtual-list虛擬列表組件來規(guī)避這個問題。另一個坑是第三方SDK兼容性比如微信支付雖然uniapp封裝了uni.requestPayment但不同端的喚起參數(shù)格式有差異這塊必須寫平臺適配代碼不能圖省事一把梭。1.3 Python后端框架怎么選Python后端可選的框架很多Flask、Django、FastAPI。我做這個項(xiàng)目選的是FastAPI理由也直接。性能FastAPI基于ASGI異步框架并發(fā)能力比Flask的WSGI模式強(qiáng)不少。零工市場高峰期往往集中在上午和晚飯后用戶瞬間刷單量比較大異步IO能扛住。自動生成接口文檔FastAPI內(nèi)置Swagger文檔寫完接口就能在瀏覽器里調(diào)試前后端聯(lián)調(diào)效率高很多。對于一人開發(fā)的個人項(xiàng)目來說這功能太省事了。類型校驗(yàn)Pydantic做的請求參數(shù)校驗(yàn)寫清楚類型注解前端傳錯參數(shù)馬上能看出來問題。生態(tài)兼容SQLAlchemy 2.0的異步版本跟FastAPI配合得很好數(shù)據(jù)庫操作不阻塞事件循環(huán)。要說缺點(diǎn)FastAPI的小眾程度確實(shí)不如Flask遇到問題網(wǎng)上搜到的資料少一些。但官方文檔寫得很清楚上手成本并不高。我用它寫這個項(xiàng)目整體體驗(yàn)比用Django輕量比用Flask舒服。1.4 整體技術(shù)架構(gòu)與模塊劃分這個系統(tǒng)的完整技術(shù)鏈路是這樣小程序/App端uniapp Vue3 ↓ HTTPS/JSON 后端APIFastAPI Uvicorn ↓ SQLAlchemy ORM MySQL 8.0業(yè)務(wù)數(shù)據(jù) ↓ Redis緩存、驗(yàn)證碼、分布式鎖 ↓ 對象存儲OSS用戶頭像、零工圖片、憑證業(yè)務(wù)模塊劃分我一開始就定了七個用戶模塊微信登錄、手機(jī)號綁定、身份切換雇主/工人、資質(zhì)信息零工模塊發(fā)布需求、需求大廳列表、條件篩選、關(guān)鍵詞搜索訂單模塊報(bào)名/接單、雇主確認(rèn)、訂單狀態(tài)流轉(zhuǎn)、取消與異常處理結(jié)算模塊微信支付V3、資金托管、完工打款、退款評價模塊雙向評價、信用分消息模塊系統(tǒng)通知、接單提醒主要是訂閱消息管理后臺審核零工單、處理糾紛、用戶管理模塊之間通過訂單狀態(tài)這個“總線”串起來這也是我拆解整個系統(tǒng)時最花心思的地方。2. 數(shù)據(jù)庫設(shè)計(jì)先把業(yè)務(wù)變成表2.1 核心表結(jié)構(gòu)拆解數(shù)據(jù)庫是業(yè)務(wù)的底座表設(shè)計(jì)得好不好直接決定后期開發(fā)爽不爽。我前后改了三個版本最后定下來的核心表有這些。用戶表userid、openid微信唯一標(biāo)識、unionid、nickname、avatar、phone、role1-雇主、2-工人、3-雙身份、credit_score、status1-正常、2-封禁。這里要說明的是微信小程序登錄時用wx.login拿的是code用來換openid但用戶手機(jī)號需要單獨(dú)點(diǎn)擊授權(quán)按鈕才能拿到所以phone字段是后期補(bǔ)充的。零工表gig_orderid、user_id發(fā)布者ID、title標(biāo)題、description描述、category工種分類、province/city/district地區(qū)、address詳細(xì)地址、longitude/latitude經(jīng)緯度、budget_low/budget_high預(yù)算區(qū)間、start_time/end_time預(yù)計(jì)工作時段、need_count需要人數(shù)、skill_tag技能要求、status1-招聘中、2-已滿、3-已完成、4-已取消、view_count瀏覽量。報(bào)名/接單表gig_applyid、gig_order_id、user_id申請人、price報(bào)價金額、message自我介紹、status1-待確認(rèn)、2-已接受、3-已拒絕、4-已完成、created_at。交易表transactionid、gig_order_id、employer_id、worker_id、amount、pay_status1-待支付、2-已托管、3-已打款、4-已退款、pay_time、settle_time。評價表reviewid、gig_order_id、from_user_id、to_user_id、rating1-5分、content、created_at。這里有一個容易踩的坑零工單和訂單要不要拆成兩張表我的做法是拆開的。零工表是“需求信息”報(bào)名表里被雇主確認(rèn)的那個申請記錄才升級成“訂單”。為什么要拆因?yàn)橐粋€零工單可以被多個工人報(bào)名但最終可能只需要一個人。如果直接在零工表里存“誰接單”就存不下多個人報(bào)名的記錄后面做提名、候補(bǔ)、取消接單就很被動。拆成兩張表之后gig_apply表的status已接受那條記錄就相當(dāng)于“臨時履約合同”。2.2 訂單狀態(tài)機(jī)設(shè)計(jì)別讓業(yè)務(wù)亂成一鍋粥這塊是系統(tǒng)最核心的地方。零工訂單的狀態(tài)流轉(zhuǎn)我用狀態(tài)機(jī)精確控制后端接收每一次狀態(tài)變更時先校驗(yàn)“當(dāng)前狀態(tài) 操作事件”是否合法不合法直接拒絕。標(biāo)準(zhǔn)流轉(zhuǎn)路徑招聘中 → 報(bào)名 → 雇主確認(rèn) → 已接單 → 工人開工 → 驗(yàn)收完成 → 已結(jié)算 → 已評價允許的跳轉(zhuǎn)招聘中 → 已取消雇主主動撤銷且報(bào)名人數(shù)為0已接單 → 已取消雙方協(xié)商或超時未開工雇主可取消已接單 → 驗(yàn)收完成工人提交完工雇主確認(rèn)驗(yàn)收完成 → 已結(jié)算結(jié)算模塊打款成功后更新狀態(tài)我在代碼里實(shí)現(xiàn)時用的是一個TransitionDict# 狀態(tài)機(jī)定義 STATE_TRANSITIONS { recruiting: {apply, cancel}, assigned: {start, cancel, complete}, completed: {settle}, settled: {review}, }狀態(tài)機(jī)的好處是后端代碼里到處是if gig.status xxx這種判斷根本沒法維護(hù)狀態(tài)機(jī)把規(guī)則收斂到一個地方邏輯清晰出bug的概率也小。2.3 結(jié)算與錢包邏輯零工市場做結(jié)算最忌諱的是“平臺先收款再打款”的模式被用戶誤解為資金池。我的設(shè)計(jì)里引入了**交易單transaction**這種表結(jié)構(gòu)把平臺的賬目邏輯獨(dú)立出來。交易流程是雇主確認(rèn)工人后先調(diào)微信支付V3托管這筆錢狀態(tài)已托管→ 工人完工、雇主確認(rèn)驗(yàn)收后平臺觸發(fā)結(jié)算狀態(tài)已打款。這里特別注意打款人不是平臺自己而是通過微信支付的商家轉(zhuǎn)賬接口把托管的款項(xiàng)轉(zhuǎn)給工人。整個鏈路中平臺不碰資金只是傳遞微信支付的結(jié)果。資金安全上還要加一道“對賬”。每天跑一個定時任務(wù)把微信支付賬單和本地transaction表對比金額不一致就告警。這個功能是小程序上線后必須做的否則資金差錯根本發(fā)現(xiàn)不了。3. 后端API設(shè)計(jì)與核心接口實(shí)現(xiàn)3.1 用FastAPI搭建項(xiàng)目骨架后端項(xiàng)目我按模塊拆成這樣的目錄結(jié)構(gòu)app/ ├── main.py # 應(yīng)用入口、路由注冊 ├── config.py # 配置項(xiàng)數(shù)據(jù)庫、Redis、微信參數(shù) ├── models/ # SQLAlchemy ORM模型 ├── schemas/ # Pydantic請求/響應(yīng)模型 ├── api/ # 路由模塊 │ ├── user.py │ ├── gig.py │ ├── order.py │ ├── pay.py │ └── review.py ├── services/ # 業(yè)務(wù)邏輯層 ├── core/ # 安全、依賴注入、微信SDK封裝 └── tests/ # 單元測試入口文件不復(fù)雜關(guān)鍵是把中間件、CORS、路由掛載好from fastapi import FastAPI from fastapi.middleware.cors import CORSMiddleware from app.api import user, gig, order, pay, review app FastAPI(title零工市場服務(wù)系統(tǒng), version1.0.0) app.add_middleware( CORSMiddleware, allow_origins[*], allow_methods[*], allow_headers[*], ) app.include_router(user.router, prefix/api/user, tags[用戶]) app.include_router(gig.router, prefix/api/gig, tags[零工]) app.include_router(order.router, prefix/api/order, tags[訂單]) app.include_router(pay.router, prefix/api/pay, tags[支付]) app.include_router(review.router, prefix/api/review, tags[評價]) app.get(/health) def health_check(): return {status: ok}3.2 零工發(fā)布與列表接口發(fā)布零工接口是寫操作里最核心的我做了比較嚴(yán)格的參數(shù)校驗(yàn)。注意Pydantic模型里budget_low和budget_high要校驗(yàn)大小關(guān)系start_time要在當(dāng)前時間之后。class GigCreate(BaseModel): title: str Field(..., min_length4, max_length50) description: str Field(, max_length500) category: str city: str district: str address: str longitude: float latitude: float budget_low: Decimal budget_high: Decimal start_time: datetime end_time: datetime need_count: int Field(1, ge1, le10) skill_tag: str model_validator(modeafter) def check_budget(self): if self.budget_high self.budget_low: raise ValueError(預(yù)算上限不能低于下限) if self.end_time self.start_time: raise ValueError(結(jié)束時間必須晚于開始時間) return self列表接口做的是“綜合排序 篩選”。用戶在大廳里默認(rèn)看到的是離我最近、預(yù)算合適、快要開工的單子排前面。SQL的排序邏輯用權(quán)重計(jì)算SELECT * FROM gig_order WHERE status 1 AND city 上海市 AND category IN (搬家, 搬運(yùn)) AND start_time NOW() ORDER BY (budget_high - budget_low) DESC, start_time ASC LIMIT 20 OFFSET 0實(shí)際實(shí)現(xiàn)時我用了SQLAlchemy的動態(tài)查詢構(gòu)造器前端每次傳不同的篩選條件后端動態(tài)拼SQL。這里有個經(jīng)驗(yàn)篩選條件能傳參數(shù)就用參數(shù)不確定就做成索引字段比如category、city、status三個字段一定要建聯(lián)合索引不然數(shù)據(jù)量上來后這個接口必掛。3.3 接單與訂單鎖定并發(fā)是重災(zāi)區(qū)零工接單跟電商搶購很像尤其在熱門的好單子上可能同時有幾十個人報(bào)名。報(bào)名動作本身并發(fā)量不大真正危險的是“雇主確認(rèn)工人”那一刻——同一個零工單如果被兩個雇主操作不太可能但為了防止臟讀或者同一個工人被兩個人同時確認(rèn)就會產(chǎn)生超賣。我用了Redis分布式鎖來防并發(fā)import redis.asyncio as aioredis redis_client aioredis.from_url(redis://localhost:6379/0) async def confirm_worker(gig_id: int, worker_id: int): lock_key fgig_confirm:{gig_id} # 加鎖5秒超時 acquired await redis_client.set(lock_key, 1, nxTrue, ex5) if not acquired: raise HTTPException(status_code409, detail操作太頻繁請稍后重試) try: # 檢查零工單狀態(tài)是否還是“招聘中” gig await get_gig(gig_id) if gig.status ! recruiting: raise HTTPException(status_code400, detail該零工已滿或已關(guān)閉) # 更新報(bào)名表狀態(tài) # 更新零工狀態(tài)為“已接單” ... finally: await redis_client.delete(lock_key)這種鎖的方案能擋住絕大多數(shù)并發(fā)問題。更保險的方案是用MySQL的行鎖SELECT ... FOR UPDATE但我會優(yōu)先用Redis鎖因?yàn)橹辉诖_認(rèn)這個動作上做短鎖數(shù)據(jù)庫壓力小。3.4 微信登錄與JWT鑒權(quán)微信小程序的登錄流程是固定套路前端wx.login()拿code→ 傳給后端 → 后端用code換openidsession_key→ 返回自定義登錄態(tài)。這里我再套一層JWT用戶每次請求帶上Token后端通過依賴注入拿到當(dāng)前用戶ID。app.post(/api/user/login) async def login(request: LoginRequest): # 1. 獲取openid url https://api.weixin.qq.com/sns/jscode2session params { appid: WECHAT_APPID, secret: WECHAT_SECRET, js_code: request.code, grant_type: authorization_code, } async with httpx.AsyncClient() as client: resp await client.get(url, paramsparams) data resp.json() if errcode in data: raise HTTPException(status_code400, detail微信登錄失敗) openid data[openid] # 2. 查或建用戶 user await get_user_by_openid(openid) if not user: user await create_user(openid) # 3. 生成JWT token jwt.encode({uid: user.id, exp: time.time() 7 * 24 * 3600}, SECRET_KEY, algorithmHS256) return {token: token, user_info: user} # 全局依賴獲取當(dāng)前用戶 async def get_current_user(token: str Depends(oauth2_scheme)): try: payload jwt.decode(token, SECRET_KEY, algorithms[HS256]) uid payload.get(uid) except Exception: raise HTTPException(status_code401, detail登錄已過期) user await get_user_by_id(uid) if not user: raise HTTPException(status_code401, detail用戶不存在) return user這套東西不算難但有一個點(diǎn)要注意JWT的secret必須跟業(yè)務(wù)配置分開從環(huán)境變量讀取不要硬編碼在代碼倉庫里。另一個點(diǎn)是openid不能直接當(dāng)用戶ID用因?yàn)橛脩粼谛〕绦蚶锴袚Q手機(jī)號或者換綁openid會變所以要在用戶表里單獨(dú)建自增ID作為主鍵。4. 前端核心功能實(shí)現(xiàn)4.1 頁面結(jié)構(gòu)規(guī)劃前端用uniapp Vue3 Pinia頁面結(jié)構(gòu)不復(fù)雜但tabBar的設(shè)計(jì)比較講究。零工市場有兩個核心角色我用了“身份切換”的思路而不是給雇主和工人各做一套獨(dú)立App。tabBar三個頁簽首頁零工大廳默認(rèn)是“找零工”模式顯示零工列表發(fā)布中間一個大按鈕點(diǎn)擊后先讓用戶選擇身份若是雇主角色則進(jìn)入發(fā)布表單若沒有雇主身份引導(dǎo)切換我的個人信息、我的發(fā)布、我的接單、錢包、設(shè)置這個設(shè)計(jì)的好處是用戶不需要重新下載或切換小程序一個App里完成雇主和工人的雙角色切換。代碼層面用Pinia里的userStore.role控制頁面展示。4.2 列表頁與下拉刷新、觸底加載零工大廳是流量最大的頁面做不好用戶體驗(yàn)全毀。我用的方案是首次進(jìn)入加載20條滑動到底部自動加載下一頁頂部下拉刷新。注意uniapp中H5端可以通過onReachBottom鉤子實(shí)現(xiàn)觸底加載小程序端同樣支持這塊API是統(tǒng)一的。結(jié)構(gòu)大致如下template view classgig-list view v-foritem in gigList :keyitem.id classgig-card clickgoDetail(item.id) view classgig-title{{ item.title }}/view view classgig-meta text{{ item.category }}/text text{{ item.city }}{{ item.district }}/text text{{ item.start_time }}/text /view view classgig-budget text￥{{ item.budget_low }}-{{ item.budget_high }}/text /view /view view v-ifloading classloading加載中.../view /view /template這里有一個經(jīng)驗(yàn)圖片懶加載要開。零工卡片如果有圖片直接用uniapp的image lazy-load組件否則列表滾動的時候會明顯卡頓。另外列表數(shù)據(jù)量大了以后建議用z-paging這種現(xiàn)成的分頁組件幫我處理空數(shù)據(jù)、錯誤、加載狀態(tài)省很多事。4.3 發(fā)布頁與地圖定位發(fā)布零工時用戶需要選地址和標(biāo)記定位。這塊我用uniapp內(nèi)置的uni.chooseLocation它可以拉起微信內(nèi)置地圖選擇器。但有幾個坑要提前規(guī)避uni.chooseLocation在小程序端必須配置permission里的scope.userLocation否則第一次調(diào)用會直接fail。經(jīng)緯度和地址名是兩個字段不能只存地址名否則列表頁做距離排序就沒數(shù)據(jù)可用。發(fā)布表單里工作地址支持input手填和坐標(biāo)選擇兩種方式手填地址如果沒選坐標(biāo)后端要能夠容忍經(jīng)緯度為空的場景但排序時這些單子排到最后。我之前踩過一個坑真機(jī)調(diào)試時uni.chooseLocation返回的經(jīng)緯度是gcj02坐標(biāo)系的如果直接傳給后端存庫再交給騰訊地圖SDK做逆地理編碼坐標(biāo)會有偏差。這里要統(tǒng)一坐標(biāo)系建議地圖組件、后端存儲、逆地理編碼都用gcj02坐標(biāo)系別跟GPS原始坐標(biāo)混用。4.4 用戶身份切換與個人中心身份切換在“我的”頁面里做。用戶一開始是游客登錄后默認(rèn)身份是“工人”。要發(fā)零工單需要切換到“雇主”身份第一次切換時彈窗讓他補(bǔ)全雇主信息比如真實(shí)姓名、聯(lián)系電話。個人中心要展示的信息分兩大塊作為雇主我發(fā)布的零工單列表 每個單的報(bào)名人員作為工人我報(bào)名的零工單列表 接單記錄我用Tab切換實(shí)現(xiàn)這兩種視圖列表請求不同接口。切換身份時后端要做校驗(yàn)如果當(dāng)前用戶有進(jìn)行中的零工單作為雇主未取消、作為工人報(bào)名未完成不允許切換身份否則會導(dǎo)致訂單列表混亂。5. 微信支付V3對接實(shí)戰(zhàn)5.1 對接前準(zhǔn)備微信支付V3是現(xiàn)在小程序支付的主流方案相比V2V3的密鑰體系更安全API采用RSA簽名。先說對接前的準(zhǔn)備清單微信小程序賬號個人主體不行必須是企業(yè)/個體工商戶微信支付商戶號需要企業(yè)資質(zhì)商戶API私鑰在商戶平臺生成要妥善保管APIv3密鑰商戶平臺設(shè)置用于回調(diào)報(bào)文解密微信支付平臺證書用于驗(yàn)證微信回調(diào)簽名密鑰這塊必須強(qiáng)調(diào)一點(diǎn)私鑰不要上傳到代碼倉庫更不要hardcode在前端。正確的做法是放在后端服務(wù)器環(huán)境變量或KMS密鑰管理服務(wù)里。uniapp端喚起支付用的是uni.requestPayment它需要后端返回paySign等一系列參數(shù)。流程是用戶點(diǎn)擊“確認(rèn)接單”后前端把gig_order_id傳給后端 → 后端調(diào)微信支付統(tǒng)一下單接口 → 拿到prepay_id后端用預(yù)支付ID生成paySign→ 返回給前端前端調(diào)起支付面板。5.2 統(tǒng)一下單與回調(diào)解密我在后端封裝了一個支付service核心邏輯是把下單、簽名、回調(diào)、解密各拆成一個函數(shù)。統(tǒng)一下單的關(guān)鍵參數(shù)如下# 微信支付V3統(tǒng)一下單核心參數(shù) payload { appid: WECHAT_APPID, # 小程序appid mchid: MCH_ID, # 商戶號 description: f零工單付款-{gig_id}, out_trade_no: trade_no, # 業(yè)務(wù)訂單號全局唯一 notify_url: https://api.xxx.com/api/pay/notify, amount: { total: int(amount * 100), # 單位是分一定要乘100 currency: CNY }, payer: {openid: user_openid}, # 用戶openid }這里特容易犯一個錯金額單位搞錯。微信支付V3的total字段單位是“分”不是“元”。我用Decimal類型在數(shù)據(jù)庫里存金額元到調(diào)用支付接口時再轉(zhuǎn)成整數(shù)分避免浮點(diǎn)誤差。支付回調(diào)處理是整套支付鏈路里最不能出錯的地方。微信服務(wù)器會把支付結(jié)果以POST方式推送到我們配置的notify_url這個接口必須做好兩件事一是驗(yàn)簽二是解密資源數(shù)據(jù)。app.post(/api/pay/notify) async def wechat_pay_notify(request: Request): headers request.headers body await request.body() # 1. 驗(yàn)簽用微信平臺證書驗(yàn)證請求頭里的Wechatpay-Signature verify_wechat_signature(headers, body) # 2. 解析body得到resource對象 resource json.loads(body)[resource] # 3. 解密resource.ciphertext得到訂單數(shù)據(jù) plaintext decrypt_resource(resource) data json.loads(plaintext) # 4. 修改交易單狀態(tài) await handle_pay_success(data[out_trade_no], data[transaction_id]) # 5. 返回給微信“成功”響應(yīng) return {code: SUCCESS, message: 成功}回調(diào)處理接口是冪等的微信可能因?yàn)榫W(wǎng)絡(luò)問題重復(fù)推送回調(diào)所以handle_pay_success里一定要做“如果已經(jīng)處理過就直接返回成功”的判斷不然后端會重復(fù)給工人打款。5.3 退款與時延處理用戶取消訂單、雇主取消訂單都可能涉及退款。退款走微信支付V3的退款接口金額不能超過原支付金額且必須注明退款原因。退款接口是異步的微信會返回refund_status: PROCESSING最終結(jié)果通過回調(diào)通知。所以退款狀態(tài)也要在數(shù)據(jù)庫里實(shí)時記錄PROCESSING→SUCCESS/ABNORMAL。我在管理后臺做了一張退款記錄表方便財(cái)務(wù)對賬。這里有一個運(yùn)營層面的坑不要直接對還沒支付成功的單子發(fā)起退款。比如用戶在支付面板里點(diǎn)了支付但沒完成支付就退出了此時交易單狀態(tài)是“待支付”前端不要誘導(dǎo)用戶走退款直接重新發(fā)起支付就行。只有狀態(tài)為“已托管”的訂單在取消時才走退款流程。5.4 支付對接常見異常做支付對接這段時間我整理了三個高頻異常都是真實(shí)踩過的“商戶號未配置該產(chǎn)品權(quán)限”原因是簽約的產(chǎn)品權(quán)限還沒生效或者小程序appid沒有綁定商戶號。在商戶平臺的“產(chǎn)品中心”里確認(rèn)已開通JSAPI支付并且小程序appid和商戶號是關(guān)聯(lián)狀態(tài)?！案犊畲a無效”或“用戶未授權(quán)”前端調(diào)uni.requestPayment時多半是后端返回的timeStamp、nonceStr、package參數(shù)格式不對。特別注意package字段的值是prepay_idxxx前面必須帶prepay_id前綴不能只傳ID。支付回調(diào)收不到檢查notify_url是否公網(wǎng)可訪問域名必須備案且是小程序后臺配置的合法域名。本地開發(fā)時我用了natapp做內(nèi)網(wǎng)穿透來測試回調(diào)但上線前一定要換成正式的HTTPS域名。還有一個最重要的提醒小程序的支付能力跟小程序的類目和資質(zhì)強(qiáng)綁定。零工市場屬于“居民服務(wù)/生活服務(wù)”類目需要提供營業(yè)執(zhí)照等資質(zhì)。如果小程序因?yàn)槠渌虮幌拗浦Ц侗热珙惸坎粚?、主體資質(zhì)未過審所有支付接口都會報(bào)錯所以支付功能務(wù)必在上線前就打磨好不要等到發(fā)布后發(fā)現(xiàn)用戶沒法付款。6. 打包發(fā)布與常見問題排查6.1 uniapp打包微信小程序流程uniapp打包小程序不算難但流程中有幾個容易忽略的環(huán)節(jié)。按照這個步驟來基本不會翻車在HBuilderX里選擇“運(yùn)行到小程序模擬器”還是“發(fā)行到微信小程序”平時開發(fā)用運(yùn)行模式發(fā)布用發(fā)行模式。發(fā)行前檢查manifest.json里的小程序appid是否正確這個appid必須是注冊好的小程序appid不能是測試號。在微信公眾平臺里配置request合法域名和uploadFile合法域名后端接口域名必須在這里白名單否則小程序里網(wǎng)絡(luò)請求全部被攔截。用HBuilderX發(fā)行后生成dist/build/mp-weixin目錄然后用微信開發(fā)者工具導(dǎo)入這個目錄提交審核。審核周期一般1-7天個人主體的話類目審核可能更嚴(yán)。零工市場這個類目建議申請時選“生活服務(wù) 其他生活服務(wù)”然后準(zhǔn)備軟件著作權(quán)證書。我第一次提審的時候被拒了兩次原因都是“類目與資質(zhì)不符”后來上傳了軟件著作權(quán)材料并且把“接單”頁的交互邏輯做完整才過審。6.2 真機(jī)調(diào)試與打包常見報(bào)錯真機(jī)調(diào)試連不上確保手機(jī)和電腦在同一局域網(wǎng)微信開發(fā)者工具選擇了“真機(jī)調(diào)試”并且小程序后臺把開發(fā)者本人的微信號加為體驗(yàn)成員。打包后請求全部404大概率是環(huán)境變量問題。我在config.js里同時寫了devBaseUrl和prodBaseUrl打包時用環(huán)境變量切到正式域名。樣式錯亂uniapp的rpx單位在小屏上比較正常但某些安卓機(jī)的WebView渲染有差異。我的處理辦法是所有多行文本統(tǒng)一用text-overflow: ellipsis加-webkit-line-clamp做截?cái)啾苊饪ㄆ叨炔灰恢乱疱e位。iOS上輸入框被軟鍵盤頂上去這是uniapp老坑尤其是評論區(qū)或發(fā)布頁的textarea在iOS Safari上會被軟鍵盤頂飛。解決方法是設(shè)置adjust-positionfalse自己監(jiān)聽軟鍵盤彈起高度來調(diào)整輸入框位置我封裝了一個keyboard-height的mixins來解決。6.3 分享被覆蓋與自定義分享實(shí)現(xiàn)微信小程序的分享功能如果不做任何處理默認(rèn)是分享整個頁面。但在零工市場里用戶更希望分享“某個零工單詳情頁”給朋友或微信群。我用onShareAppMessage實(shí)現(xiàn)自定義分享內(nèi)容但遇到一個坑小程序內(nèi)部定義了全局的分享方法各頁面如果沒有單獨(dú)覆蓋就會走全局邏輯。我的做法是在每個需要分享的頁面重寫onShareAppMessage并且加一個shareTicket判斷支持群分享后通過wx.getShareInfo獲取群ID這樣方便后端做“群派單”場景的統(tǒng)計(jì)分析。// 零工詳情頁 onShareAppMessage() { const gigId this.gigId; return { title: 零工${this.gigTitle}, path: /pages/gig/detail?id${gigId}, imageUrl: this.gigCover, }; }這里提醒一個細(xì)節(jié)path里的參數(shù)必須是query形式不能是params形式否則分享點(diǎn)進(jìn)來后onLoad里取不到參數(shù)。6.4 上線前的自檢清單項(xiàng)目要真正上線我列了一個自檢清單貼出來供大家對照微信支付回調(diào)路徑為公網(wǎng)HTTPS域名且證書有效后端接口全部走HTTPS且只暴露最小化端口數(shù)據(jù)庫啟動自動備份每天凌晨全量備份一次用戶敏感信息手機(jī)號、姓名在數(shù)據(jù)庫加密存儲敏感接口修改余額、提現(xiàn)做了操作日志和審計(jì)前端所有圖片都開啟了懶加載列表接口做了分頁限流后臺管理端只能通過白名單IP訪問零工單審核機(jī)制已上線防止虛假招聘信息以上任何一條出問題都可能導(dǎo)致小程序?qū)徍耸』蛘哂脩敉对V。尤其第二條現(xiàn)在微信對數(shù)據(jù)安全的審查越來越嚴(yán)不符合要求會直接讓小程序下架。7. 零工市場系統(tǒng)的后續(xù)擴(kuò)展方向最后聊一點(diǎn)我對這套系統(tǒng)后續(xù)演進(jìn)的想法。首版跑通之后零工市場服務(wù)系統(tǒng)還可以往這幾個方向擴(kuò)展。第一個方向是智能匹配。目前前端還停留在列表刷單的模式下一步可以基于用戶的技能標(biāo)簽、歷史接單數(shù)據(jù)、當(dāng)前定位用推薦算法把“工人可能感興趣的零工單”推到首頁。這不需要多復(fù)雜的模型先做基于標(biāo)簽的召回再按距離排序體驗(yàn)就會好不少。第二個方向是信用體系升級。目前評價系統(tǒng)還算基礎(chǔ)后續(xù)可以引入行為信譽(yù)分比如“無責(zé)取消扣分”“按時到崗加分”分?jǐn)?shù)高的工人在列表里優(yōu)先展示雇主評分低的用戶發(fā)布零工時需要上傳押金。這個機(jī)制能極大減少交易糾紛。第三個方向是企業(yè)級服務(wù)接口。零工市場的單體小程序做到一定規(guī)模可以開放給勞務(wù)公司、商家讓他們通過API批量發(fā)布用工需求平臺按撮合成功抽傭。這種企業(yè)端的接口設(shè)計(jì)需要和C端做權(quán)限隔離技術(shù)上可以基于OAuth2.0做授權(quán)。從需求分析到數(shù)據(jù)庫設(shè)計(jì)再到前后端聯(lián)調(diào)、支付對接、上線審核這套零工市場系統(tǒng)走完了一個完整的產(chǎn)品生命周期。整個過程中我最大的體會是這類撮合平臺的技術(shù)難點(diǎn)不在某個單點(diǎn)功能而在狀態(tài)管理和資金安全這兩條主線上。狀態(tài)機(jī)設(shè)計(jì)得清楚前后端聯(lián)調(diào)效率翻倍支付流程每一步都嚴(yán)謹(jǐn)上線后才敢安心睡覺。希望這篇文章能給正在做類似項(xiàng)目的人一些參考少走幾步彎路。