1. 從“能跑”到“跑得穩(wěn)”代碼工廠的優(yōu)化動(dòng)機(jī)先說(shuō)個(gè)背景。我之前在某公司帶著團(tuán)隊(duì)維護(hù)一個(gè)內(nèi)部的服務(wù)端工程Go 寫(xiě)的壓在一套 PostgreSQL 上。Go 這門(mén)語(yǔ)言寫(xiě)業(yè)務(wù)確實(shí)利索但日子久了問(wèn)題就冒出來(lái)了每次新增一張表都要手寫(xiě) model、dao、query、handler 這一整套模板代碼表一多復(fù)制粘貼都嫌煩。更要命的是PostgreSQL 的一些類(lèi)型比如數(shù)組、JSONB、區(qū)間類(lèi)型跟 Go 的結(jié)構(gòu)體字段映射起來(lái)很別扭手寫(xiě)一遍兩遍還行寫(xiě)多了必然出錯(cuò)。于是我們當(dāng)時(shí)就做了一個(gè)內(nèi)部工具姑且叫“Go代碼工廠”。它的核心功能很簡(jiǎn)單連上 PostgreSQL 的庫(kù)讀 information_schema把表結(jié)構(gòu)、字段類(lèi)型、索引、主鍵、外鍵這些元信息抓出來(lái)然后按模板批量生成 Go 的 entity、mapper、service 和簡(jiǎn)單的 CRUD 接口。工具上線之后開(kāi)發(fā)效率確實(shí)上來(lái)了新表落地從“半天”變成“五分鐘”。但用了半年大家開(kāi)始抱怨“生成的代碼能跑但不好用?！边@就是我寫(xiě)這篇文章的出發(fā)點(diǎn)。代碼生成工具不難做難的是“生成出來(lái)的代碼在真實(shí)生產(chǎn)環(huán)境里經(jīng)得起折騰”。這篇文章不聊怎么搭一個(gè)簡(jiǎn)單的模板引擎那網(wǎng)上教程一抓一大把。我想講的是我們?yōu)榱俗屗嬲m配 PostgreSQL踩過(guò)哪些坑、優(yōu)化了哪些細(xì)節(jié)、為什么這么改以及最后沉淀下來(lái)的這套可復(fù)用的實(shí)踐方案。需要這套方案的人我猜主要是有這么幾類(lèi)一是團(tuán)隊(duì)內(nèi)部想搞代碼生成器但沒(méi)頭緒的二是已經(jīng)在用生成器但覺(jué)得生成代碼質(zhì)量不行的三是純粹想了解 Go 訪問(wèn) PostgreSQL 時(shí)那些性能細(xì)節(jié)的同學(xué)。不管你屬于哪類(lèi)這篇文章應(yīng)該都有點(diǎn)參考價(jià)值。2. 整體架構(gòu)與關(guān)鍵設(shè)計(jì)取舍2.1 代碼工廠的分層結(jié)構(gòu)先把我們最終敲定的結(jié)構(gòu)畫(huà)出來(lái)你就知道優(yōu)化點(diǎn)都藏在哪兒了。整個(gè)工具分四層元數(shù)據(jù)抓取層負(fù)責(zé)連庫(kù)讀取 PostgreSQL 的系統(tǒng)表得到表、字段、約束、索引、注釋等信息類(lèi)型映射層把 PostgreSQL 的數(shù)據(jù)類(lèi)型映射到 Go 的類(lèi)型這是最容易出錯(cuò)的一層模板渲染層基于映射結(jié)果填充 Go 代碼模板輸出 entity、dao、service、handler輸出/落盤(pán)層處理文件的輸出路徑、包名、格式化、冪等覆蓋策略這四層各管各的互相之間只通過(guò)結(jié)構(gòu)化數(shù)據(jù)傳遞信息。最初版本不是這樣最初我把模板渲染和元數(shù)據(jù)抓取耦合在一起模板里直接寫(xiě) SQL 查詢(xún)結(jié)果就是換一個(gè)數(shù)據(jù)庫(kù)版本模板就要?jiǎng)右槐榫S護(hù)成本極高。優(yōu)化后的第一原則就是元數(shù)據(jù)層只產(chǎn)生結(jié)構(gòu)化的中間表示模板層只消費(fèi)這份穩(wěn)定的結(jié)構(gòu)體。后面你要支持 MySQL、SQLite只需要替換元數(shù)據(jù)抓取層模板層完全不用動(dòng)。這個(gè)分層思路不但讓工具本身好維護(hù)也讓生成代碼的質(zhì)量更容易控制。2.2 為什么選 PostgreSQL 作為核心適配目標(biāo)可能有人問(wèn)為什么專(zhuān)門(mén)針對(duì) PostgreSQL 做優(yōu)化MySQL 不香嗎這里有個(gè)很現(xiàn)實(shí)的原因PostgreSQL 的數(shù)據(jù)類(lèi)型體系比 MySQL 復(fù)雜得多。MySQL 基本就是 int、varchar、datetime 這些幾乎都能直接對(duì)應(yīng)到 Go 基礎(chǔ)類(lèi)型上。PostgreSQL 呢有numeric、uuid、jsonb、int4range、tsvector、citext、枚舉類(lèi)型、數(shù)組類(lèi)型……如果映射策略不做對(duì)生成的代碼要么編譯不過(guò)要么運(yùn)行時(shí) panic要么出現(xiàn)嚴(yán)重的隱性類(lèi)型轉(zhuǎn)換性能問(wèn)題。舉個(gè)例子PostgreSQL 的numeric類(lèi)型在 Go 里直接映射成float64是最偷懶的做法但在涉及金額、精度要求高的場(chǎng)景下float64 的精度問(wèn)題會(huì)直接污染業(yè)務(wù)數(shù)據(jù)。我們一開(kāi)始就吃過(guò)這個(gè)虧后來(lái)強(qiáng)制規(guī)范為numeric必須映射成string或shopspring/decimal類(lèi)型具體取決于使用場(chǎng)景。這類(lèi)問(wèn)題如果你不做專(zhuān)門(mén)適配光靠通用模板是永遠(yuǎn)發(fā)現(xiàn)不了的。另外PostgreSQL 的索引類(lèi)型和 SQL 語(yǔ)法也有不少“非標(biāo)準(zhǔn)”的地方比如ILIKE、jsonb_path_query、DISTINCT ON這些在生成查詢(xún)條件時(shí)如果不考慮進(jìn)去生成的 DAO 層代碼就只能覆蓋最簡(jiǎn)單的場(chǎng)景稍微復(fù)雜一點(diǎn)的業(yè)務(wù)需求就要手工改那就失去代碼工廠的意義了。2.3 設(shè)計(jì)取舍表驅(qū)動(dòng)還是字段驅(qū)動(dòng)我們?cè)诘羞€做了一個(gè)重要的設(shè)計(jì)決策生成代碼時(shí)默認(rèn)按“單表主鍵驅(qū)動(dòng)”來(lái)生成基礎(chǔ) CRUD但生成結(jié)果不綁定死。什么意思呢就是工具生成的代碼默認(rèn)支持FindByPrimaryKey、Insert、UpdateByPrimaryKey、DeleteByPrimaryKey、PageQuery這幾個(gè)方法所有方法都基于主鍵展開(kāi)。但對(duì)于沒(méi)有主鍵的表PostgreSQL 允許不建主鍵工具會(huì)自動(dòng)降級(jí)為“全字段等值查詢(xún)”模式同時(shí)會(huì)在生成的代碼注釋里明確打上警告標(biāo)記提示開(kāi)發(fā)者手動(dòng)補(bǔ)充。這個(gè)取舍的價(jià)值在于它讓生成的代碼在一個(gè)可控的范式內(nèi)保持一致性又不會(huì)因?yàn)椤斑^(guò)度自適應(yīng)”導(dǎo)致生成結(jié)果不可預(yù)測(cè)。代碼生成工具最怕的就是“玄學(xué)生成”同樣的輸入換個(gè)環(huán)境生成的東西不一樣那還不如不搞。3. 核心細(xì)節(jié)拆解那些決定成敗的小事3.1 類(lèi)型映射的最終規(guī)則表這是整個(gè)工具的核心我直接給出踩坑后沉淀下來(lái)的映射規(guī)則。先說(shuō)好這不是唯一的正確答案但這是我們?cè)趯?shí)際生產(chǎn)環(huán)境里打磨過(guò)的版本。PostgreSQL 類(lèi)型Go 類(lèi)型默認(rèn)可選類(lèi)型說(shuō)明smallint/int2int16int一般業(yè)務(wù)用int更省心但嚴(yán)格按寬度更好integer/int4int32int同上看團(tuán)隊(duì)規(guī)范bigint/int8int64string雪花 ID 這類(lèi)超長(zhǎng) ID 建議 stringnumeric/decimaldecimal.Decimalstring涉及金額、精度絕不建議 floatreal/float4float32float64一般場(chǎng)景直接用 float64double precision/float8float64--booleanbool--text/varchar(n)string--char(n)string-記得處理 TrimSpaceuuidstringuuid.UUID推薦 string避免引入依賴(lài)json/jsonb[]bytejson.RawMessage/ 自定義 struct別默認(rèn)映射成 stringdatetime.Timestring注意時(shí)區(qū)問(wèn)題timestamp/timestamptztime.Time-timestamptz要小心時(shí)區(qū)bytea[]byte--數(shù)組類(lèi)型如text[][]stringpq.Array/pgx原生支持視驅(qū)動(dòng)而定枚舉類(lèi)型string自定義類(lèi)型生成常量注釋這套映射表看著簡(jiǎn)單細(xì)節(jié)全在坑里。拿jsonb來(lái)說(shuō)很多初版工具會(huì)把它映射成string然后業(yè)務(wù)里到處json.Unmarshal([]byte(obj.Field))。一旦字段值為 null或者 PostgreSQL 返回的 jsonb 帶了格式縮進(jìn)寫(xiě)出來(lái)的代碼就花式報(bào)錯(cuò)。我們后來(lái)統(tǒng)一映射成[]byte并且在模板里生成一個(gè)Scan的輔助方法自動(dòng)處理 null 和錯(cuò)誤包裝這個(gè)問(wèn)題才算根治。再說(shuō)timestamptz。如果你用的驅(qū)動(dòng)是lib/pq掃出來(lái)的是一個(gè)time.Time但時(shí)區(qū)信息可能會(huì)被吞掉換到pgx就好很多。我們?cè)谀０謇锬J(rèn)生成一個(gè)注釋提醒開(kāi)發(fā)者所有時(shí)間字段統(tǒng)一用 UTC 存儲(chǔ)由 API 層做時(shí)區(qū)轉(zhuǎn)換。這是很實(shí)用的團(tuán)隊(duì)規(guī)范代碼生成工具就該承載這種規(guī)范而不是只翻譯類(lèi)型。3.2 元數(shù)據(jù)抓取的 SQL 細(xì)節(jié)讀 PostgreSQL 元數(shù)據(jù)最核心的一條 SQL 是查字段信息。我這里有兩條比較成熟的查詢(xún)語(yǔ)句一條是查表基礎(chǔ)信息一條是查字段列表直接在information_schema和pg_catalog上跑。-- 查表基礎(chǔ)信息 SELECT c.relname AS table_name, obj_description(c.oid) AS table_comment FROM pg_class c JOIN pg_namespace n ON n.oid c.relnamespace WHERE n.nspname public -- 指定 schema避免不小心掃到系統(tǒng)表 AND c.relkind r -- 只取普通表排除視圖、物化視圖等 ORDER BY c.relname;-- 查字段信息 SELECT a.attname AS column_name, format_type(a.atttypid, a.atttypmod) AS data_type, a.attnotnull AS not_null, COALESCE(col_description(a.attrelid, a.attnum), ) AS column_comment, CASE WHEN pk.attname IS NOT NULL THEN true ELSE false END AS is_primary_key, CASE WHEN a.attidentity a THEN true ELSE false END AS is_identity, COALESCE(( SELECT pg_get_expr(d.adbin, d.adrelid) FROM pg_attrdef d WHERE d.adrelid a.attrelid AND d.adnum a.attnum ), ) AS default_expr FROM pg_attribute a JOIN pg_class c ON c.oid a.attrelid JOIN pg_namespace n ON n.oid c.relnamespace LEFT JOIN ( SELECT conrelid, attname FROM pg_constraint JOIN pg_attribute ON pg_attribute.attnum ANY(pg_constraint.conkey) AND pg_attribute.attrelid pg_constraint.conrelid WHERE pg_constraint.contype p ) pk ON pk.conrelid a.attrelid AND pk.attname a.attname WHERE n.nspname public AND c.relname $1 AND a.attnum 0 AND NOT a.attisdropped ORDER BY a.attnum;這段 SQL 是優(yōu)化過(guò)程中反復(fù)調(diào)整出來(lái)的。有幾個(gè)細(xì)節(jié)值得注意format_type(a.atttypid, a.atttypmod)會(huì)把varchar(255)這種帶長(zhǎng)度的類(lèi)型也格式化出來(lái)這樣類(lèi)型映射層就能拿到完整的聲明自己決定要不要截?cái)嚅L(zhǎng)度信息。主鍵的識(shí)別方式我一開(kāi)始用information_schema.table_constraints關(guān)聯(lián)key_column_usage去查后來(lái)發(fā)現(xiàn)慢改成直接在pg_constraint上查contype p更快也更準(zhǔn)確。attidentity是用來(lái)判斷自增列的。PostgreSQL 10 之后推薦的GENERATED AS IDENTITY在這里能識(shí)別出來(lái)但老的serial類(lèi)型不在這里體現(xiàn)要額外看default_expr是否包含nextval(。這個(gè)細(xì)節(jié)在生成 Insert 語(yǔ)句時(shí)非常關(guān)鍵否則會(huì)把自增列拼進(jìn)去導(dǎo)致主鍵沖突。3.3 模板引擎選型標(biāo)準(zhǔn)庫(kù)就夠了模板引擎我們沒(méi)引入第三方的用的就是 Go 標(biāo)準(zhǔn)庫(kù)text/template。很多人覺(jué)得標(biāo)準(zhǔn)庫(kù)功能不夠強(qiáng)想上pongo2或jet但我們對(duì)比過(guò)之后還是堅(jiān)持了標(biāo)準(zhǔn)庫(kù)。原因很簡(jiǎn)單代碼工廠的模板邏輯復(fù)雜度有限無(wú)非就是range循環(huán)字段、if判斷類(lèi)型、拼字符串標(biāo)準(zhǔn)庫(kù)都覆蓋了減少依賴(lài)工具本身的構(gòu)建和分發(fā)會(huì)簡(jiǎn)單很多標(biāo)準(zhǔn)庫(kù)的模板執(zhí)行性能雖然不算頂尖但生成代碼這個(gè)場(chǎng)景是低頻操作性能根本不敏感真正需要花心思的是模板的組織。我們調(diào)整后的模板目錄結(jié)構(gòu)是templates/ ├── entity.go.tmpl // 實(shí)體結(jié)構(gòu)體 ├── dao.go.tmpl // 數(shù)據(jù)訪問(wèn)層含基礎(chǔ) CRUD ├── query.go.tmpl // 擴(kuò)展查詢(xún)基于條件構(gòu)造 ├── service.go.tmpl // 業(yè)務(wù)服務(wù)層包裝事務(wù) ├── handler.go.tmpl // HTTP 處理器 ├── router.go.tmpl // 路由注冊(cè) └── partials/ ├── common.go.tmpl // 通用導(dǎo)入、錯(cuò)誤處理等 └── field_convert.go.tmpl // 字段轉(zhuǎn)換輔助函數(shù)每個(gè)表生成的文件就是把這些模板用同一個(gè)數(shù)據(jù)對(duì)象渲染出來(lái)。注意同一個(gè)模板文件會(huì)被多次渲染但數(shù)據(jù)不同所以模板中絕不能寫(xiě)死表名、字段名。我們?cè)?jīng)在某個(gè)模板里偷懶直接把表名寫(xiě)死在模板注釋里結(jié)果生成第二個(gè)表的時(shí)候注釋全部錯(cuò)亂排查了半天才發(fā)現(xiàn)是模板緩存的問(wèn)題。標(biāo)準(zhǔn)庫(kù)模板沒(méi)有內(nèi)置的“繼承”機(jī)制但你可以用{{define xxx}}定義子模板在主模板里{{template xxx .}}引用。我們就是這樣把公共的error handling部分抽成 partials避免每個(gè)模板都重復(fù)一坨if err ! nil的邏輯。4. 針對(duì) PostgreSQL 的深度功能優(yōu)化4.1 批量 Insert 的生成策略PostgreSQL 的批量插入有幾種方式逐條INSERT、單條INSERT拼接多組VALUES、COPY協(xié)議。代碼工廠默認(rèn)生成的是第二種也就是帶多組 values 的單條 SQL因?yàn)檫@種方式兼容性最好也便于在生成代碼里做參數(shù)綁定。但在生成時(shí)我們需要處理一個(gè) PostgreSQL 特有的限制參數(shù)占位符$N的編號(hào)是全局遞增的不能像某些數(shù)據(jù)庫(kù)那樣每組 values 都從$1重新開(kāi)始。所以模板里必須維護(hù)一個(gè)“參數(shù)序號(hào)”的累加器。INSERT INTO {{.TableName}} ({{range .InsertableFields}}{{.Name}}, {{end}}) VALUES {{range $i, $row : .Rows}} (${{$offset : add (mul $i (len $.InsertableFields)) 1}}... {{end}}這段模板代碼的邏輯就是第i行的第一個(gè)參數(shù)序號(hào)是i * 字段數(shù) 1每行內(nèi)部的字段序號(hào)依次遞增。這個(gè)看起來(lái)很簡(jiǎn)單的計(jì)算如果不注意生成的 SQL 參數(shù)編號(hào)就會(huì)亂掉。我們?cè)诔醢婢筒攘诉@個(gè)坑實(shí)際跑起來(lái)之后發(fā)現(xiàn) PostgreSQL 報(bào)bind message supplies 0 parameters的錯(cuò)誤排查日志才知道序號(hào)對(duì)不上。除了參數(shù)編號(hào)批量Insert還有一個(gè)經(jīng)驗(yàn)值可以分享單批插入的行數(shù)并非越多越好。我們壓測(cè)下來(lái)在普通云數(shù)據(jù)庫(kù)實(shí)例上每批 200 到 500 行之間性能比較穩(wěn)定再往上提升有限反而可能因?yàn)閱未?SQL 過(guò)大觸發(fā)網(wǎng)絡(luò)層問(wèn)題。所以在生成的代碼里我們默認(rèn)按 300 行一批做切片并且把這個(gè)值設(shè)計(jì)成了常量方便開(kāi)發(fā)者在調(diào)用處覆蓋。4.2 JSONB 字段的查詢(xún)寫(xiě)法PostgreSQL 的jsonb是很多團(tuán)隊(duì)的“心頭好”因?yàn)闃I(yè)務(wù)數(shù)據(jù)加字段太方便了。但代碼工廠生成的 DAO 層如果只支持“where field ?”jsonb 的作用就廢了一半。我們優(yōu)化時(shí)特意針對(duì)方括號(hào)和對(duì)象嵌套查詢(xún)移植了 Postgres 的原生能力。生成的查詢(xún)代碼支持兩種 jsonb 查詢(xún)方式// 第一種對(duì)象字段等值匹配 SELECT * FROM orders WHERE payload - status $1; // 第二種路徑提取匹配 SELECT * FROM orders WHERE payload # {user, profile, name} $1;在查詢(xún)構(gòu)造器的模板里我們根據(jù)字段元數(shù)據(jù)里的一個(gè)約定來(lái)自動(dòng)選擇寫(xiě)法字段名以jsonb_前綴開(kāi)頭的生成路徑查詢(xún)代碼否則生成普通等值查詢(xún)。這個(gè)約定簡(jiǎn)單粗暴但團(tuán)隊(duì)里執(zhí)行起來(lái)零成本比搞一堆配置項(xiàng)好用。這里要提醒一句jsonb查詢(xún)盡量走 GIN 索引。我們生成的 migration 文件里會(huì)默認(rèn)給jsonb字段加上USING gin (字段名 jsonb_ops)的索引建議但不會(huì)強(qiáng)制創(chuàng)建。選擇權(quán)交給業(yè)務(wù)方因?yàn)樗饕筒樵?xún)模式的匹配度只有業(yè)務(wù)最清楚。4.3 UPSERT 的模板支持PostgreSQL 的ON CONFLICT DO UPDATE語(yǔ)法在實(shí)現(xiàn)業(yè)務(wù)冪等寫(xiě)入時(shí)非常好用。代碼工廠為每個(gè)表生成一個(gè)Upsert方法模板里顯式聲明沖突目標(biāo)為主鍵或唯一索引func (d *XxxDao) Upsert(ctx context.Context, e *XxxEntity) (int64, error) { sqlStr : INSERT INTO xxx (id, name, payload) VALUES ($1, $2, $3) ON CONFLICT (id) DO UPDATE SET name EXCLUDED.name, payload EXCLUDED.payload, updated_at now() // 執(zhí)行并返回影響行數(shù) }這里有個(gè)細(xì)節(jié)點(diǎn)DO UPDATE只會(huì)更新傳入的非主鍵字段主鍵字段在沖突時(shí)保持不變。這樣設(shè)計(jì)是為了避免一個(gè)常見(jiàn)的并發(fā)陷阱——兩條帶同一個(gè)業(yè)務(wù)鍵的請(qǐng)求先后到達(dá)如果不加保護(hù)后一條可能把前一條的主鍵或者創(chuàng)建時(shí)間覆蓋掉。模板生成時(shí)所有非主鍵字段都會(huì)出現(xiàn)在SET列表里保證“全字段覆蓋式更新”語(yǔ)義清晰。另外ON CONFLICT后面的目標(biāo)列必須是唯一的。如果表上沒(méi)有唯一索引生成的代碼在 PostgreSQL 會(huì)直接報(bào)錯(cuò)。為了不讓工具生成“必壞代碼”我們?cè)谠獢?shù)據(jù)抓取階段就檢查了表上的唯一約束如果一張表既沒(méi)有主鍵、也沒(méi)有唯一約束就不生成Upsert方法而是把方法名留空同時(shí)在生成的日志中打一條告警。這個(gè)“能做才生成不做就明確提示”的原則后來(lái)幫團(tuán)隊(duì)避了不少雷。4.4 分頁(yè)查詢(xún)的排序穩(wěn)定性PostgreSQL 的LIMIT/OFFSET分頁(yè)有一個(gè)經(jīng)典問(wèn)題如果排序字段不是唯一的翻頁(yè)時(shí)可能出現(xiàn)數(shù)據(jù)重復(fù)或者丟失。比如按created_at排序而同一時(shí)間戳有多條記錄那么每頁(yè)的邊界就會(huì)漂移。代碼工廠生成的PageQuery方法對(duì)此做了兩件事第一默認(rèn)排序字段不只是你指定的排序鍵還會(huì)自動(dòng)追加主鍵作為次排序鍵。比如SELECT * FROM xxx ORDER BY created_at DESC, id DESC LIMIT $1 OFFSET $2;這樣可以保證分頁(yè)結(jié)果在邏輯上是“穩(wěn)定排序”的。第二排序字段默認(rèn)白名單機(jī)制。生成的代碼不會(huì)接受任意字符串作為排序字段而是從元數(shù)據(jù)里把合法的字段名列出來(lái)傳入排序字段如果不在白名單里直接返回參數(shù)錯(cuò)誤。這既防了 SQL 注入也防了手滑寫(xiě)錯(cuò)列名的低級(jí) bug。5. 連接池和數(shù)據(jù)庫(kù)訪問(wèn)參數(shù)優(yōu)化5.1 pgx 驅(qū)動(dòng)是更好的選擇說(shuō)到 Go 連 PostgreSQL初期我們用的lib/pq后來(lái)全部遷到了pgx。不是lib/pq不好而是pgx在底層性能、類(lèi)型支持和協(xié)議利用上確實(shí)更勝一籌。遷移之后最明顯的變化有兩個(gè)pgx使用 PostgreSQL 原生的二進(jìn)制格式傳輸數(shù)據(jù)在傳輸大數(shù)據(jù)量的bytea、jsonb時(shí)性能比文本格式快不少pgx支持自動(dòng)讀取 PostgreSQL 的類(lèi)型信息自定義類(lèi)型、數(shù)組類(lèi)型都能直接映射到 Go 的切片和結(jié)構(gòu)體省掉了我們自己寫(xiě)一堆轉(zhuǎn)換函數(shù)的功夫連接池這塊我們用的是pgxpool。配置參數(shù)經(jīng)過(guò)幾輪壓測(cè)調(diào)整后固定下來(lái)一套相對(duì)穩(wěn)妥的初始值poolConfig, _ : pgxpool.ParseConfig(dsn) poolConfig.MaxConns 20 poolConfig.MinConns 2 poolConfig.MaxConnLifetime 30 * time.Minute poolConfig.MaxConnIdleTime 5 * time.Minute poolConfig.HealthCheckPeriod 1 * time.Minute這里每個(gè)參數(shù)都有說(shuō)道。MaxConns不是越大越好PostgreSQL 的每個(gè)連接都是一個(gè)進(jìn)程連接數(shù)過(guò)多反而會(huì)造成上下文切換開(kāi)銷(xiāo)。我們有同事把MaxConns直接配成 100結(jié)果數(shù)據(jù)庫(kù) CPU 沒(méi)上去反而是連接管理和鎖等待把性能拖垮了。一般經(jīng)驗(yàn)是連接數(shù) 機(jī)器核數(shù) * (2 到 3) 磁盤(pán)等待系數(shù)具體還是要壓測(cè)。MaxConnLifetime設(shè) 30 分鐘是因?yàn)?PostgreSQL 后端連接太長(zhǎng)時(shí)間不換會(huì)被云數(shù)據(jù)庫(kù)或防火墻悄然斷開(kāi)客戶(hù)端這邊如果不感知就會(huì)報(bào)broken pipe之類(lèi)的錯(cuò)誤設(shè)置連接生命周期可以規(guī)避這種情況。5.2 預(yù)編譯語(yǔ)句的取舍pgx是默認(rèn)使用 prepared statement 的也就是預(yù)編譯。好處是 SQL 解析只做一次執(zhí)行更快壞處是連接較多、SQL 模式特別多的情況下prepared statement 會(huì)占用服務(wù)端內(nèi)存。代碼工廠生成的 DAO 層里所有Insert、Update、Delete方法使用的 SQL 模式都是固定的這是 prepared statement 的最佳使用場(chǎng)景。但查詢(xún)類(lèi)方法因?yàn)闂l件動(dòng)態(tài)拼接一個(gè)方法可能產(chǎn)生幾十種 SQL 變體這時(shí)候如果還是無(wú)條件啟用 prepared statement服務(wù)端緩存就會(huì)膨脹。我們的處理策略是代碼工廠生成的 DAO 層里查詢(xún)方法統(tǒng)一走Exec/Query的非預(yù)編譯路徑只有固定的寫(xiě)操作走預(yù)編譯。具體在pgx里就是通過(guò)pgx.QueryExecModeSimpleProtocol之類(lèi)的配置來(lái)控制模式或者在 SQL 拼接后直接調(diào)用帶pgx.QueryRewriter的接口。這樣既穩(wěn)住了寫(xiě)操作的性能又不讓查詢(xún)模式把服務(wù)端緩存打爆。5.3 超時(shí)控制必須生成代碼工廠生成的每個(gè) DAO 方法第一個(gè)參數(shù)都是context.Context這一點(diǎn)特別重要。生成代碼里所有數(shù)據(jù)庫(kù)操作都會(huì)帶上這個(gè) context并且模板中強(qiáng)制生成context.WithTimeout的調(diào)用位置。評(píng)論區(qū)看到過(guò)不少“數(shù)據(jù)庫(kù)連接泄漏”的案例十有八九是 context 沒(méi)傳。代碼工廠用模板從源頭把這條路堵住所有方法簽名必須有一個(gè)ctx參數(shù)所有Query、Exec調(diào)用前統(tǒng)一defer cancel()。這套“消失的 defer”我們已經(jīng)在生成層實(shí)現(xiàn)了不用開(kāi)發(fā)者每次手寫(xiě)。在超時(shí)值的選擇上默認(rèn)給的是5 * time.Second。有人可能覺(jué)得 5 秒太長(zhǎng)但在我們實(shí)際業(yè)務(wù)中有些復(fù)雜查詢(xún)確實(shí)會(huì)跑 2 到 3 秒5 秒算一個(gè)比較穩(wěn)妥的保守值。具體到慢查詢(xún)場(chǎng)景開(kāi)發(fā)者可以在調(diào)用時(shí)傳入自定義的 withTimeout 覆蓋默認(rèn)值模板提供這個(gè)口子。6. 實(shí)操過(guò)程與踩坑實(shí)錄6.1 一個(gè)典型的表生成全流程演示光說(shuō)理論不直觀拿一個(gè)具體例子走一遍整個(gè)流程。假設(shè)我們有張user_profile表CREATE TABLE user_profile ( id BIGINT GENERATED ALWAYS AS IDENTITY PRIMARY KEY, nickname VARCHAR(64) NOT NULL, email CITEXT UNIQUE, avatar_url TEXT, settings JSONB DEFAULT {}::jsonb, created_at TIMESTAMPTZ NOT NULL DEFAULT now(), updated_at TIMESTAMPTZ NOT NULL DEFAULT now() );跑代碼工廠的命令行codegen --db postgres://user:passlocalhost:5432/app --schema public --table user_profile --output ./internal/model工具會(huì)在內(nèi)部執(zhí)行我們前面說(shuō)的元數(shù)據(jù)查詢(xún)得到字段信息后自動(dòng)生成entity.go、user_profile_dao.go、user_profile_service.go、router.go。打開(kāi)看entity 大概長(zhǎng)這樣type UserProfile struct { ID int64 json:id Nickname string json:nickname Email string json:email AvatarURL string json:avatar_url,omitempty Settings json.RawMessage json:settings CreatedAt time.Time json:created_at UpdatedAt time.Time json:updated_at }注意Email映射成的就是string因?yàn)閏itext類(lèi)型在驅(qū)動(dòng)里本來(lái)就會(huì)作為文本處理。Settings映射成json.RawMessage而不是string這就避免了手動(dòng)強(qiáng)轉(zhuǎn)的麻煩。DAO 層的PageQuery方法生成的長(zhǎng)這樣func (d *UserProfileDao) PageQuery(ctx context.Context, req PageRankReq) (*PageRankResp, error) { // 排序字段白名單校驗(yàn) if !d.sortableFields[req.SortField] { return nil, ErrInvalidSortField } sqlStr : SELECT * FROM user_profile WHERE ($1 OR nickname ILIKE % || $1 || %) ORDER BY req.SortField req.SortOrder , id DESC LIMIT $2 OFFSET $3 // ... }從命名到寫(xiě)法這套代碼都是能直接進(jìn) code review 的。我們團(tuán)隊(duì)內(nèi)部做過(guò)一次統(tǒng)計(jì)代碼工廠生成的文件評(píng)審時(shí)被打回的比率遠(yuǎn)低于手寫(xiě)代碼主要原因就是模板層面已經(jīng)把常見(jiàn)問(wèn)題全部規(guī)避了。6.2 初期版本踩過(guò)的三個(gè)典型坑第一個(gè)坑jsonb 字段被當(dāng)作普通字符串處理。初版生成的 DAO查jsonb字段直接是WHERE settings $1但 JSONB 的內(nèi)部二進(jìn)制格式和文本并不總是嚴(yán)格相等導(dǎo)致某些場(chǎng)景查不到數(shù)據(jù)。后來(lái)改成settings::text $1或走包含操作符才徹底解決。第二個(gè)坑帶時(shí)區(qū)的時(shí)間字段被搞錯(cuò)。我們的數(shù)據(jù)庫(kù)統(tǒng)一存的是 UTC 時(shí)間但生成的 Go 代碼在讀取timestamptz後直接格式化輸出有的環(huán)境自動(dòng)轉(zhuǎn)成了本地時(shí)區(qū)前端看到的時(shí)間就差了 8 小時(shí)。現(xiàn)在模板里生成時(shí)間字段時(shí)會(huì)自動(dòng)調(diào)用一個(gè)formatTime輔助函數(shù)強(qiáng)制以 UTC 格式輸出并且在注釋里寫(xiě)明約定這個(gè)坑就再?zèng)]犯過(guò)。第三個(gè)坑生成文件覆蓋導(dǎo)致手寫(xiě)代碼丟失。代碼工廠用的模板文件是穩(wěn)定的但業(yè)務(wù)一旦在生成文件上做了二次開(kāi)發(fā)比如加了幾個(gè)自定義方法下次跑工具整個(gè)文件被覆蓋辛辛苦苦寫(xiě)的代碼就沒(méi)了。后來(lái)我們加了一個(gè)保護(hù)機(jī)制生成文件開(kāi)頭統(tǒng)一寫(xiě)入“Code generated by codegen. DO NOT EDIT.”標(biāo)記工具在覆蓋前檢查這個(gè)標(biāo)記如果沒(méi)有這個(gè)標(biāo)記就跳過(guò)覆蓋并提示開(kāi)發(fā)者手動(dòng)合并。這個(gè)策略極大減少了大伙的“工傷”。此外還有一個(gè) SQL 大小寫(xiě)的問(wèn)題。PostgreSQL 默認(rèn)會(huì)把未加引號(hào)的標(biāo)識(shí)符折疊成小寫(xiě)如果生成的 SQL 里表名、字段名帶了大小寫(xiě)混合并且沒(méi)有用雙引號(hào)括起來(lái)就會(huì)報(bào) “relation does not exist”。模板中我們對(duì)所有標(biāo)識(shí)符統(tǒng)一做了小寫(xiě)處理避免這種低級(jí)錯(cuò)誤。6.3 生成代碼的性能驗(yàn)證方法代碼生成完性能過(guò)關(guān)不過(guò)關(guān)不能拍腦袋。我建議大家在工具里直接內(nèi)置一個(gè)自檢模式生成完代碼后自動(dòng)跑一輪輕量級(jí)基準(zhǔn)測(cè)試。具體做法是生成一個(gè)_test.go文件里面放幾個(gè)基礎(chǔ)的 CRUD 基準(zhǔn)測(cè)試用例專(zhuān)門(mén)測(cè)批量插入吞吐量、分頁(yè)查詢(xún)延遲、UPSERT 并發(fā)穩(wěn)定性這三項(xiàng)。我們的經(jīng)驗(yàn)數(shù)值大致是批量插入 5000 行耗時(shí)控制在 1.5 秒內(nèi)分頁(yè)查詢(xún) 10 萬(wàn)行數(shù)據(jù)單次延遲低于 100 毫秒U(xiǎn)PSERT 并發(fā) 50 個(gè) goroutine 跑 10 分鐘不出現(xiàn)鎖等待超時(shí)。達(dá)不到這些數(shù)值就該回頭檢查數(shù)據(jù)庫(kù)索引、連接池配置或模板生成的 SQL 了。這種方法的好處是把“代碼質(zhì)量關(guān)”前移到了生成階段而不是等業(yè)務(wù)上線后才發(fā)現(xiàn)。代碼工廠成了開(kāi)發(fā)流程里的一環(huán)而不是一個(gè)“跑完就忘”的腳本。7. 常見(jiàn)問(wèn)題與排查思路速查我把實(shí)際運(yùn)維中遇到過(guò)的高頻問(wèn)題整理成一張表方便你排查問(wèn)題時(shí)對(duì)著看問(wèn)題現(xiàn)象可能原因排查方法/解決方案生成的代碼編譯報(bào)錯(cuò)字段類(lèi)型不匹配類(lèi)型映射規(guī)則沒(méi)覆蓋到特殊類(lèi)型檢查format_type返回的原始類(lèi)型字符串加入映射表檢查是否映射成了interface{}改為具體類(lèi)型運(yùn)行時(shí)報(bào)bind message supplies 0 parameters批量 Insert 的參數(shù)編號(hào)累加邏輯錯(cuò)誤打印最終 SQL 和參數(shù)列表檢查$N編號(hào)是否連續(xù)遞增查詢(xún)jsonb字段查不到數(shù)據(jù)直接用了等值比較未考慮 jsonb 內(nèi)部格式改用操作符或者字段先::text做等值轉(zhuǎn)換分頁(yè)翻頁(yè)重復(fù)/丟失數(shù)據(jù)ORDER BY字段不唯一追加主鍵字段作為次排序鍵長(zhǎng)時(shí)間運(yùn)行后出現(xiàn)broken pipe連接被服務(wù)端靜默回收設(shè)置MaxConnLifetime定期刷新連接ON CONFLICT報(bào)錯(cuò)no unique or exclusion constraint matching表上無(wú)主鍵或唯一索引元數(shù)據(jù)層檢查唯一約束不生成Upsert時(shí)間字段差 8 小時(shí)時(shí)區(qū)轉(zhuǎn)換被默認(rèn)環(huán)境時(shí)區(qū)影響強(qiáng)制在 DAO 層將時(shí)間格式化為 UTC 輸出重新生成代碼后手寫(xiě)部分丟失覆蓋策略過(guò)于激進(jìn)生成文件頭部加DO NOT EDIT標(biāo)記覆蓋前檢查標(biāo)記生成的enum類(lèi)型無(wú)法映射自定義枚舉類(lèi)型沒(méi)定義生成常量列表和類(lèi)型定義映射為 string并附帶合法值注釋這些問(wèn)題的根源大多數(shù)不是 Go 本身而是對(duì) PostgreSQL 數(shù)據(jù)模型的理解不夠細(xì)。代碼工廠只是把這份理解固化成了模板讓團(tuán)隊(duì)里每個(gè)開(kāi)發(fā)者不用重復(fù)踩坑。8. 這套方案的擴(kuò)展思路與實(shí)際體會(huì)代碼工廠這套思路不只適用于 PostgreSQL。后來(lái)我們用它接 MySQL發(fā)現(xiàn)只要把元數(shù)據(jù)抓取層換成 MySQL 系統(tǒng)表的查詢(xún)類(lèi)型映射做一次擴(kuò)展模板基本不用動(dòng)。再往后團(tuán)隊(duì)還想接入 Redis 的數(shù)據(jù)結(jié)構(gòu)生成器我提出復(fù)用分層架構(gòu)只改元數(shù)據(jù)層效果也不錯(cuò)。這說(shuō)明初始的分層設(shè)計(jì)才是整個(gè)工具最重要的部分它決定了后續(xù)所有優(yōu)化的空間。關(guān)于“代碼生成到底該不該用”我個(gè)人有些不同的看法。網(wǎng)上常有人爭(zhēng)論手寫(xiě)代碼和生成代碼誰(shuí)更好我覺(jué)得這是偽問(wèn)題。代碼工廠不是用來(lái)取代開(kāi)發(fā)者的它是把那些重復(fù)、機(jī)械、容易出錯(cuò)的部分自動(dòng)完成讓人把時(shí)間和精力騰出來(lái)處理真正的業(yè)務(wù)邏輯。但代碼工廠也有邊界。它適合生成 CRUD 這種高度模式化的代碼但不適合生成復(fù)雜的業(yè)務(wù)編排和領(lǐng)域邏輯硬把業(yè)務(wù)規(guī)則塞進(jìn)模板里只會(huì)得到一個(gè)“什么都想管、什么都做不好”的四不像。所以我在實(shí)際使用中一直堅(jiān)持一個(gè)原則工具負(fù)責(zé)提供可靠的“積木”業(yè)務(wù)層自己搭樂(lè)高。最后分享一個(gè)可能很多人都沒(méi)意識(shí)到的小技巧代碼工廠生成的代碼最好直接納入 CI 流水線做一次“編譯 格式校驗(yàn) 靜態(tài)檢查”。我們?cè)趯?shí)踐里把代碼生成做成了一個(gè) CI 步驟每次元數(shù)據(jù)有變更、模板有調(diào)整都自動(dòng)跑一遍生成代碼的變化會(huì)在 MR 里清楚展示出來(lái)。這比讓開(kāi)發(fā)者在本地跑工具靠譜得多因?yàn)楸镜丨h(huán)境千奇百怪有人是 Windows有人用 Docker搞到最后生成結(jié)果不一致問(wèn)題都出在“本地還跑得好好的”這句話上。有了 CI 兜底代碼工廠才真正變成了團(tuán)隊(duì)基礎(chǔ)設(shè)施的一部分。