ROADMAP

B11 · 資料驗證與序列化 詳細 ROADMAP

計畫文件，不會被 Quartz 渲染。 回主 roadmap → backend/ROADMAP.md

---

章節目標

「不信任來自外部的資料」是後端信條。本章涵蓋 input validation 策略（boundary vs everywhere）、schema 工具（Zod / Pydantic / JSR-380 / Valibot）、序列化格式（JSON / Protobuf / MsgPack）、DTO vs Entity 分離、以及跨語言 schema 共用。

---

🌱 基本介紹

#	主題	Slug	Stage	大綱
01	資料驗證與序列化是什麼	01-what-is-validation-serialization	🌱	輸入驗證 / 輸出序列化 / 內部 DTO 三件事的分工

---

❓ 為什麼需要

#	主題	Slug	Stage	大綱
02	為什麼 input validation 不是有驗就好	02-why-validation-not-just-presence	🌱	你驗 length 但沒驗 format；驗 int 但沒驗 range；驗 enum 但沒驗 case；driven by attacker，不是 driven by usability
03	為什麼 DTO 必須跟 Entity 分開	03-why-dto-vs-entity	🌱	DB schema 洩漏、敏感欄位回傳給 client（password_hash 出現在 response）、前後端耦合

---

🕰️ 演進

#	主題	Slug	Stage	大綱
04	Schema 工具演進	04-schema-tool-evolution	🌱	手寫 validator → JSR-303/380（Java）→ Joi（JS）→ Pydantic（Python）→ Zod / Valibot 崛起（2022+）
05	序列化格式演進	05-serialization-evolution	🌱	XML → JSON 主流 → Protobuf（2008）→ MessagePack / Avro / FlatBuffers；gRPC 帶動 Protobuf 復興

---

🧠 知識型

F11-A Input Validation

#	主題	Slug	Stage	大綱
06	Boundary vs Everywhere validation	06-boundary-vs-everywhere	🌱	只在邊界驗 vs 每層都驗；trust boundary 設計
07	Schema-first validation	07-schema-first-validation	🌱	宣告式 schema（Zod / Pydantic）vs 程序式；auto error message；跟 OpenAPI 整合
08	跨語言 Schema 工具	08-cross-language-schema	🌱	Zod（TS）vs Pydantic（Py）vs JSR-380（Java）vs DataAnnotations（.NET）vs Valibot（輕量 TS）
09	Custom validator 設計	09-custom-validator	🌱	跟業務邏輯整合；為什麼不該在 validator 做 DB 查詢
10	跨 field / async validation	10-cross-field-async-validation	🌱	兩個 field 互相依賴、async 驗 unique email；各 framework 支援度
10-2	Validator vs Resource 職責分工	10-2-validator-vs-resource	🌱	Validator（驗型別 / 範圍 / 格式）、Resource（驗業務規則 / 權限 / 存在性）、Transformer（轉換格式）三者責任；避免 validator 做 DB query 或權限檢查；FastAPI Depends() / Laravel FormRequest / Django serializer 各自混法

F11-B 序列化

#	主題	Slug	Stage	大綱
11	JSON 基礎與坑	11-json-pitfalls	🌱	大整數精度（JavaScript 53-bit）、Date 沒標準格式、undefined vs null、循環參考
12	Protobuf 深入	12-protobuf-deep	🌱	Schema evolution、wire format、跟 JSON 效能比較
13	MessagePack / Avro / FlatBuffers	13-alternative-formats	🌱	適用場景（高效 / schema evolution / zero-copy）
14	JSON Schema	14-json-schema	🌱	JSON Schema 作為 cross-tool standard；跟 OpenAPI、Zod、Ajv 的關係
14-2	Serialization 貫穿 ORM 的完整路徑	14-2-serialization-path	🌱	Request JSON → Validator → DTO → Service → Entity → ORM → DB；反向路徑：DB → Entity → Transformer / Response Schema → JSON；每一步的序列化 / 反序列化點；避免 DB 欄位直接外洩；跟 B07 35-5 Request Lifecycle 連動

F11-C DTO / Entity / Schema 分層

#	主題	Slug	Stage	大綱
15	DTO vs Entity	15-dto-vs-entity	🌱	分層的必要性、mapper 工具（MapStruct / AutoMapper）、避免洩漏 DB 結構
16	Request / Response / Internal 三層 schema	16-three-schema-layers	🌱	Proto 的 schemas 目錄就是這個模式；每層的責任
17	Schema Versioning	17-schema-versioning	🌱	API 版本 vs schema 版本、backward / forward compat

---

🔧 小實作注意事項

#	主題	Slug	Stage	大綱
18	從 OpenAPI 生 TS / Python / Go schema	18-openapi-codegen-schema	🌱	跨 7 語言 codegen、避免手寫 duplicate
19	Zod vs Valibot vs Joi 選型	19-js-schema-tool-selection	🌱	bundle size、效能、TS 整合度、生態

---

💣 Anti-pattern

#	主題	Slug	Stage	大綱
20	驗證與序列化 Anti-patterns	20-validation-antipatterns	🌱	用字串 regex 驗 email（用庫）、validate 完改用 raw input、信任 front-end validation、DB 回傳直接塞 response（password_hash 洩漏）、schema 跟 doc 兩套不同步、用 DateTime 不用 ISO 8601

---

🧰 對應檢查工具

#	主題	Slug	Stage	大綱
21	驗證與序列化工具	21-validation-tooling	🌱	Zod / Pydantic / JSR-380 / Valibot、ajv（JSON Schema）、Protobuf compiler、MapStruct

---

📎 補充

#	主題	Slug	Stage	大綱
S01	Runtime Types（TypeScript 的 type + runtime 兩全）	s01-runtime-types	🌱	io-ts、Zod infer、TypeBox；為什麼 TS 的 type-only 不夠

---

章節進度統計

• 知識主題：21 + 1 補充 = 22 項
• 🌿 growing：0
• 🌱 seed：22

---

跨系列連結

• → backend/api-design/ B09（API 契約）
• → backend/framework/ B06（各 framework 的 validation 機制）
• → backend/conventions/ B07 #31 schema design
• → backend/security/ B16（injection 攻擊 vs validation）
• → frontend/application/ CH8 F10（前後端 schema 共用）