@umacloud/knowledge 1.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (418) hide show
  1. package/00-governance/governance-capabilities.md +557 -0
  2. package/00-governance/knowledge-map.md +39 -0
  3. package/00-governance/maintenance-policy.md +76 -0
  4. package/00-governance/review-checklist.md +81 -0
  5. package/README.md +13 -0
  6. package/ai/01-standards/agent-development-complete.md +691 -0
  7. package/ai/01-standards/llm-application-complete.md +488 -0
  8. package/ai/01-standards/mlops-complete.md +798 -0
  9. package/ai/01-standards/prompt-engineering-complete.md +646 -0
  10. package/ai/01-standards/rag-architecture-complete.md +649 -0
  11. package/ai/02-playbooks/llm-evaluation-playbook.md +847 -0
  12. package/ai/03-checklists/ai-project-checklist.md +215 -0
  13. package/ai/04-antipatterns/ai-antipatterns.md +661 -0
  14. package/ai/05-cases/case-rag-production.md +147 -0
  15. package/ai/06-glossary/ai-glossary.md +162 -0
  16. package/ai/agent-evaluation-benchmark.md +53 -0
  17. package/ai/ai-agent-memory-context-management.md +41 -0
  18. package/ai/ai-cost-capacity-optimization-playbook.md +42 -0
  19. package/ai/ai-data-security-and-compliance-playbook.md +37 -0
  20. package/ai/ai-domain-index-and-checklist.md +40 -0
  21. package/ai/ai-governance-maturity-model.md +50 -0
  22. package/ai/ai-model-selection-and-routing-strategy.md +47 -0
  23. package/ai/ai-observability-and-oncall-runbook.md +52 -0
  24. package/ai/ai-rag-engineering-playbook.md +42 -0
  25. package/ai/ai-red-team-and-safety-evaluation.md +42 -0
  26. package/ai/ai-release-readiness-and-rollback-gate.md +42 -0
  27. package/ai/llm-agent-engineering-deep-dive.md +57 -0
  28. package/ai/prompt-and-tool-guardrails.md +52 -0
  29. package/api/01-standards/enterprise-api-standards.md +198 -0
  30. package/api/01-standards/rest-api-design-guide.md +63 -0
  31. package/api/02-playbooks/api-pagination-playbook.md +93 -0
  32. package/api/02-playbooks/graphql-production-playbook.md +176 -0
  33. package/api/03-checklists/api-review-checklist.md +55 -0
  34. package/api/04-antipatterns/api-antipatterns.md +112 -0
  35. package/architecture/01-standards/api-gateway-patterns.md +496 -0
  36. package/architecture/01-standards/cloud-native-patterns.md +644 -0
  37. package/architecture/01-standards/distributed-systems-patterns.md +591 -0
  38. package/architecture/01-standards/event-driven-architecture.md +595 -0
  39. package/architecture/01-standards/microservices-patterns-complete.md +968 -0
  40. package/architecture/01-standards/microservices-patterns.md +495 -0
  41. package/architecture/01-standards/system-design-interview.md +664 -0
  42. package/architecture/02-playbooks/microservices-patterns-playbook.md +137 -0
  43. package/architecture/02-playbooks/migration-playbook.md +780 -0
  44. package/architecture/02-playbooks/system-design-playbook.md +779 -0
  45. package/architecture/03-checklists/architecture-decision-checklist.md +297 -0
  46. package/architecture/04-antipatterns/architecture-antipatterns.md +417 -0
  47. package/architecture/05-cases/case-netflix-microservices.md +413 -0
  48. package/architecture/06-glossary/architecture-glossary.md +164 -0
  49. package/architecture/adr-template-and-examples.md +38 -0
  50. package/architecture/api-gateway-deep-dive.md +1291 -0
  51. package/architecture/configuration-management.md +1162 -0
  52. package/architecture/distributed-transactions.md +1220 -0
  53. package/architecture/microservices-complete.md +735 -0
  54. package/architecture/resilience-and-disaster-patterns.md +37 -0
  55. package/architecture/service-governance.md +1198 -0
  56. package/architecture/system-architecture-deep-dive.md +37 -0
  57. package/backend/01-standards/analytics-and-growth.md +65 -0
  58. package/backend/01-standards/api-and-error-conventions.md +120 -0
  59. package/backend/01-standards/application-layering-and-packaging.md +160 -0
  60. package/backend/01-standards/auth-implementation.md +104 -0
  61. package/backend/01-standards/backend-framework-idioms.md +74 -0
  62. package/backend/01-standards/background-jobs-and-async.md +66 -0
  63. package/backend/01-standards/caching-strategies-complete.md +390 -0
  64. package/backend/01-standards/config-and-observability.md +77 -0
  65. package/backend/01-standards/data-modeling-and-persistence.md +94 -0
  66. package/backend/01-standards/django-complete.md +1765 -0
  67. package/backend/01-standards/email-and-notifications.md +64 -0
  68. package/backend/01-standards/fastapi-complete.md +925 -0
  69. package/backend/01-standards/file-upload-and-storage.md +66 -0
  70. package/backend/01-standards/graphql-api-complete.md +416 -0
  71. package/backend/01-standards/llm-application-standard.md +78 -0
  72. package/backend/01-standards/message-queue-patterns.md +379 -0
  73. package/backend/01-standards/microservices-and-distributed.md +78 -0
  74. package/backend/01-standards/nestjs-complete.md +2167 -0
  75. package/backend/01-standards/payment-integration.md +80 -0
  76. package/backend/01-standards/rate-limiting-complete.md +451 -0
  77. package/backend/01-standards/realtime-and-websocket.md +65 -0
  78. package/backend/01-standards/search-and-filtering.md +64 -0
  79. package/backend/01-standards/spring-boot-complete.md +445 -0
  80. package/backend/02-playbooks/api-design-playbook.md +718 -0
  81. package/backend/02-playbooks/email-send-playbook.md +130 -0
  82. package/backend/02-playbooks/file-upload-s3-playbook.md +153 -0
  83. package/backend/02-playbooks/typescript-enterprise-playbook.md +133 -0
  84. package/backend/02-playbooks/websocket-realtime-playbook.md +154 -0
  85. package/backend/03-checklists/api-launch-checklist.md +189 -0
  86. package/backend/04-antipatterns/backend-antipatterns.md +1051 -0
  87. package/blockchain/01-standards/blockchain-basics.md +557 -0
  88. package/blockchain/01-standards/smart-contract-development.md +1315 -0
  89. package/cicd/01-standards/deployment-and-delivery-standard.md +96 -0
  90. package/cicd/01-standards/github-actions-complete.md +473 -0
  91. package/cicd/01-standards/release-and-store-submission.md +75 -0
  92. package/cicd/02-playbooks/cicd-pipeline-playbook.md +144 -0
  93. package/cicd/02-playbooks/release-management-playbook.md +605 -0
  94. package/cicd/03-checklists/pipeline-security-checklist.md +168 -0
  95. package/cicd/04-antipatterns/cicd-antipatterns.md +589 -0
  96. package/cicd/05-cases/case-deployment-automation.md +221 -0
  97. package/cicd/05-cases/case-gitops-transformation.md +212 -0
  98. package/cicd/06-glossary/cicd-glossary.md +114 -0
  99. package/cicd/cicd-blueprint-deep-dive.md +38 -0
  100. package/cicd/release-readiness-gate.md +37 -0
  101. package/cloud-native/01-standards/container-security.md +741 -0
  102. package/cloud-native/01-standards/kubernetes-complete.md +812 -0
  103. package/cloud-native/02-playbooks/api-gateway-playbook.md +155 -0
  104. package/cloud-native/02-playbooks/gitops-with-argocd.md +760 -0
  105. package/cloud-native/02-playbooks/k8s-troubleshooting-playbook.md +1942 -0
  106. package/cloud-native/02-playbooks/message-queue-playbook.md +129 -0
  107. package/cloud-native/02-playbooks/multicloud-governance.md +726 -0
  108. package/cloud-native/02-playbooks/serverless-patterns.md +788 -0
  109. package/cloud-native/02-playbooks/service-mesh-playbook.md +612 -0
  110. package/cloud-native/02-playbooks/terraform-iac-playbook.md +143 -0
  111. package/cloud-native/03-checklists/container-security-checklist.md +431 -0
  112. package/cloud-native/03-checklists/k8s-production-readiness-checklist.md +460 -0
  113. package/cloud-native/04-antipatterns/container-antipatterns.md +660 -0
  114. package/cloud-native/04-antipatterns/k8s-antipatterns.md +743 -0
  115. package/cloud-native/05-cases/case-k8s-migration.md +478 -0
  116. package/cloud-native/05-cases/case-k8s-scaling.md +642 -0
  117. package/cloud-native/05-cases/case-k8s-security-incident.md +397 -0
  118. package/cloud-native/06-glossary/cloud-native-glossary.md +337 -0
  119. package/cross-platform/01-standards/cross-platform-frameworks.md +83 -0
  120. package/cross-platform/01-standards/platform-selection-and-architecture.md +77 -0
  121. package/data/01-standards/elasticsearch-complete.md +2098 -0
  122. package/data/01-standards/postgresql-complete.md +1613 -0
  123. package/data/01-standards/redis-complete.md +1527 -0
  124. package/data/02-playbooks/database-optimization-playbook.md +403 -0
  125. package/data/02-playbooks/elasticsearch-production-playbook.md +132 -0
  126. package/data/03-checklists/database-launch-checklist.md +187 -0
  127. package/data/04-antipatterns/database-antipatterns.md +873 -0
  128. package/data/05-cases/case-database-migration.md +310 -0
  129. package/data/06-glossary/database-glossary.md +440 -0
  130. package/data/data-governance-and-modeling-deep-dive.md +39 -0
  131. package/data-engineering/01-standards/airflow-complete.md +523 -0
  132. package/data-engineering/01-standards/kafka-complete.md +1521 -0
  133. package/data-engineering/02-playbooks/spark-etl-playbook.md +496 -0
  134. package/data-engineering/03-checklists/pipeline-launch-checklist.md +194 -0
  135. package/data-engineering/04-antipatterns/data-pipeline-antipatterns.md +684 -0
  136. package/data-engineering/05-cases/case-real-time-pipeline.md +355 -0
  137. package/data-engineering/06-glossary/data-engineering-glossary.md +429 -0
  138. package/database/01-standards/database-schema-standards.md +147 -0
  139. package/database/02-playbooks/postgresql-optimization-quick.md +52 -0
  140. package/database/02-playbooks/postgresql-performance-optimization.md +58 -0
  141. package/database/02-playbooks/postgresql-production-playbook.md +146 -0
  142. package/database/02-playbooks/redis-caching-playbook.md +117 -0
  143. package/database/03-checklists/database-review-checklist.md +50 -0
  144. package/database/04-antipatterns/database-antipatterns.md +112 -0
  145. package/design/01-standards/ui-design-system-complete.md +423 -0
  146. package/design/02-playbooks/design-handoff-playbook.md +254 -0
  147. package/design/02-playbooks/design-review-playbook.md +388 -0
  148. package/design/03-checklists/design-review-checklist.md +246 -0
  149. package/design/04-antipatterns/design-antipatterns.md +378 -0
  150. package/design/05-cases/case-design-system-adoption.md +328 -0
  151. package/design/06-glossary/design-glossary.md +329 -0
  152. package/design/ui-full-lifecycle-cross-platform-playbook.md +571 -0
  153. package/design/ux-system-deep-dive.md +38 -0
  154. package/design-systems/00-craft-rules.md +71 -0
  155. package/design-systems/aesthetic-families.md +43 -0
  156. package/design-systems/anti-ai-slop.md +162 -0
  157. package/design-systems/bold-geometric.md +120 -0
  158. package/design-systems/brutalist-bold.md +103 -0
  159. package/design-systems/editorial-clean.md +109 -0
  160. package/design-systems/glass-aurora.md +108 -0
  161. package/design-systems/modern-minimal.md +145 -0
  162. package/design-systems/premium-luxury.md +106 -0
  163. package/design-systems/product-type-design-map.md +48 -0
  164. package/design-systems/soft-warm.md +123 -0
  165. package/design-systems/tech-utility.md +113 -0
  166. package/desktop/01-standards/desktop-app-standard.md +72 -0
  167. package/desktop/01-standards/desktop-design.md +71 -0
  168. package/development/00-governance/document-template.md +41 -0
  169. package/development/01-standards/api-versioning-strategies.md +432 -0
  170. package/development/01-standards/authentication-patterns-complete.md +479 -0
  171. package/development/01-standards/css-architecture-complete.md +550 -0
  172. package/development/01-standards/database-migration-strategies.md +484 -0
  173. package/development/01-standards/elasticsearch-complete.md +347 -0
  174. package/development/01-standards/git-complete.md +371 -0
  175. package/development/01-standards/golang-complete.md +1565 -0
  176. package/development/01-standards/graphql-complete.md +298 -0
  177. package/development/01-standards/javascript-bundlers-complete.md +469 -0
  178. package/development/01-standards/javascript-typescript-complete.md +528 -0
  179. package/development/01-standards/jest-complete.md +275 -0
  180. package/development/01-standards/linux-complete.md +234 -0
  181. package/development/01-standards/logging-observability-complete.md +526 -0
  182. package/development/01-standards/microservices-communication.md +502 -0
  183. package/development/01-standards/mongodb-complete.md +406 -0
  184. package/development/01-standards/oauth2-complete.md +285 -0
  185. package/development/01-standards/performance-optimization-complete.md +289 -0
  186. package/development/01-standards/playwright-complete.md +247 -0
  187. package/development/01-standards/postgresql-complete.md +456 -0
  188. package/development/01-standards/pytest-complete.md +340 -0
  189. package/development/01-standards/python-async-programming.md +902 -0
  190. package/development/01-standards/python-complete.md +956 -0
  191. package/development/01-standards/python-decorators-complete.md +799 -0
  192. package/development/01-standards/python-design-patterns.md +2854 -0
  193. package/development/01-standards/python-packaging-distribution.md +420 -0
  194. package/development/01-standards/python-testing-strategies.md +607 -0
  195. package/development/01-standards/python-web-frameworks-comparison.md +471 -0
  196. package/development/01-standards/redis-complete.md +317 -0
  197. package/development/01-standards/rest-api-complete.md +316 -0
  198. package/development/01-standards/rust-complete.md +578 -0
  199. package/development/01-standards/typescript-advanced-types.md +1513 -0
  200. package/development/01-standards/web-security-complete.md +292 -0
  201. package/development/02-playbooks/api-design-playbook.md +810 -0
  202. package/development/02-playbooks/database-migration-playbook.md +580 -0
  203. package/development/02-playbooks/debugging-playbook.md +692 -0
  204. package/development/02-playbooks/feature-delivery-playbook.md +430 -0
  205. package/development/02-playbooks/incident-hotfix-playbook.md +387 -0
  206. package/development/02-playbooks/performance-optimization-playbook.md +531 -0
  207. package/development/02-playbooks/performance-tuning-playbook.md +652 -0
  208. package/development/02-playbooks/refactor-playbook.md +403 -0
  209. package/development/02-playbooks/release-playbook.md +469 -0
  210. package/development/03-checklists/architecture-review-checklist.md +168 -0
  211. package/development/03-checklists/data-migration-checklist.md +157 -0
  212. package/development/03-checklists/oncall-handover-checklist.md +173 -0
  213. package/development/03-checklists/pr-checklist.md +158 -0
  214. package/development/03-checklists/production-readiness-checklist.md +190 -0
  215. package/development/03-checklists/release-readiness-checklist.md +154 -0
  216. package/development/03-checklists/security-review-checklist.md +182 -0
  217. package/development/04-antipatterns/api-antipatterns.md +657 -0
  218. package/development/04-antipatterns/architecture-antipatterns.md +686 -0
  219. package/development/04-antipatterns/backend-antipatterns.md +648 -0
  220. package/development/04-antipatterns/cicd-antipatterns.md +540 -0
  221. package/development/04-antipatterns/code-smell-antipatterns.md +571 -0
  222. package/development/04-antipatterns/data-antipatterns.md +658 -0
  223. package/development/04-antipatterns/database-antipatterns.md +578 -0
  224. package/development/04-antipatterns/frontend-antipatterns.md +635 -0
  225. package/development/04-antipatterns/reliability-antipatterns.md +700 -0
  226. package/development/04-antipatterns/security-antipatterns.md +747 -0
  227. package/development/05-cases/case-api-version-migration.md +428 -0
  228. package/development/05-cases/case-authorization-hardening.md +383 -0
  229. package/development/05-cases/case-bluegreen-rollback.md +466 -0
  230. package/development/05-cases/case-cache-snowball-protection.md +485 -0
  231. package/development/05-cases/case-ci-cd-pipeline.md +544 -0
  232. package/development/05-cases/case-database-scaling.md +500 -0
  233. package/development/05-cases/case-db-hotspot-optimization.md +487 -0
  234. package/development/05-cases/case-incident-mttr-reduction.md +563 -0
  235. package/development/05-cases/case-microservice-migration.md +375 -0
  236. package/development/05-cases/case-performance-optimization.md +406 -0
  237. package/development/05-cases/case-security-incident-response.md +345 -0
  238. package/development/06-glossary/full-stack-glossary.md +166 -0
  239. package/development/09-maturity/quarterly-audit-template.md +35 -0
  240. package/development/11-ui-excellence/ui-aesthetic-system.md +41 -0
  241. package/development/11-ui-excellence/ui-engineering-excellence.md +435 -0
  242. package/development/12-scenarios/development-scenarios-guide.md +565 -0
  243. package/development/13-implementation-assets/implementation-toolkit.md +282 -0
  244. package/development/13-implementation-assets/knowledge-gates-execution.md +43 -0
  245. package/development/14-full-lifecycle/software-lifecycle-gates.md +511 -0
  246. package/development/15-lifecycle-templates/project-templates-collection.md +791 -0
  247. package/development/api-contract-and-versioning-guide.md +36 -0
  248. package/development/api-governance-complete.md +43 -0
  249. package/development/backend-engineering-complete.md +43 -0
  250. package/development/code-review-quality-complete.md +43 -0
  251. package/development/concurrency-reliability-complete.md +43 -0
  252. package/development/database-engineering-complete.md +43 -0
  253. package/development/engineering-effectiveness-complete.md +43 -0
  254. package/development/engineering-standards-deep-dive.md +38 -0
  255. package/development/frontend-engineering-complete.md +43 -0
  256. package/development/performance-capacity-complete.md +43 -0
  257. package/development/refactor-migration-complete.md +42 -0
  258. package/development/refactoring-and-techdebt-playbook.md +37 -0
  259. package/development/security-in-development-complete.md +43 -0
  260. package/devops/01-standards/cicd-pipeline-complete.md +262 -0
  261. package/devops/01-standards/docker-complete.md +1490 -0
  262. package/devops/01-standards/github-actions-complete.md +337 -0
  263. package/devops/01-standards/kubernetes-complete.md +638 -0
  264. package/devops/01-standards/terraform-complete.md +2117 -0
  265. package/devops/02-playbooks/docker-compose-playbook.md +233 -0
  266. package/devops/02-playbooks/docker-k8s-production-playbook.md +186 -0
  267. package/devops/02-playbooks/docker-production-playbook.md +952 -0
  268. package/edge-iot/01-standards/edge-iot-complete.md +473 -0
  269. package/experts/architect/api-design.md +178 -0
  270. package/experts/architect/methodology.md +124 -0
  271. package/experts/architect/security.md +75 -0
  272. package/experts/backend-lead/methodology.md +216 -0
  273. package/experts/devops/methodology.md +160 -0
  274. package/experts/frontend-lead/methodology.md +178 -0
  275. package/experts/product-manager/industry/ecommerce.md +43 -0
  276. package/experts/product-manager/industry/saas.md +40 -0
  277. package/experts/product-manager/methodology.md +97 -0
  278. package/experts/qa-lead/methodology.md +123 -0
  279. package/experts/qa-lead/test-strategy.md +128 -0
  280. package/experts/uiux-designer/methodology.md +125 -0
  281. package/frontend/01-standards/accessibility-complete.md +532 -0
  282. package/frontend/01-standards/accessibility-standard.md +74 -0
  283. package/frontend/01-standards/admin-dashboard-and-crud.md +72 -0
  284. package/frontend/01-standards/design-tokens-complete.md +444 -0
  285. package/frontend/01-standards/forms-and-validation.md +77 -0
  286. package/frontend/01-standards/frontend-architecture-and-layering.md +119 -0
  287. package/frontend/01-standards/i18n-and-localization.md +65 -0
  288. package/frontend/01-standards/nextjs-complete.md +451 -0
  289. package/frontend/01-standards/react-complete.md +713 -0
  290. package/frontend/01-standards/react-hooks-complete-guide.md +1100 -0
  291. package/frontend/01-standards/react-hooks-complete.md +1171 -0
  292. package/frontend/01-standards/seo-and-web-vitals.md +77 -0
  293. package/frontend/01-standards/state-management-complete.md +444 -0
  294. package/frontend/01-standards/vue-complete.md +499 -0
  295. package/frontend/01-standards/vue3-complete.md +2002 -0
  296. package/frontend/01-standards/web-framework-best-practices.md +64 -0
  297. package/frontend/01-standards/web-performance-complete.md +495 -0
  298. package/frontend/02-playbooks/accessibility-a11y-playbook.md +161 -0
  299. package/frontend/02-playbooks/frontend-performance-playbook.md +707 -0
  300. package/frontend/02-playbooks/i18n-internationalization-playbook.md +120 -0
  301. package/frontend/02-playbooks/performance-optimization-playbook.md +163 -0
  302. package/frontend/02-playbooks/react-nextjs-production-playbook.md +167 -0
  303. package/frontend/02-playbooks/react-state-management-playbook.md +173 -0
  304. package/frontend/03-checklists/component-quality-checklist.md +166 -0
  305. package/frontend/03-checklists/frontend-launch-checklist.md +299 -0
  306. package/frontend/04-antipatterns/frontend-antipatterns.md +886 -0
  307. package/frontend/05-cases/case-performance-optimization.md +274 -0
  308. package/harmony/01-standards/harmonyos-arkts-standard.md +75 -0
  309. package/harmony/01-standards/harmonyos-design.md +65 -0
  310. package/high-quality-engineering-playbook.md +54 -0
  311. package/incident/01-standards/incident-response-complete.md +303 -0
  312. package/incident/02-playbooks/chaos-engineering-playbook.md +883 -0
  313. package/incident/02-playbooks/postmortem-playbook.md +398 -0
  314. package/incident/03-checklists/incident-readiness-checklist.md +181 -0
  315. package/incident/04-antipatterns/incident-antipatterns.md +490 -0
  316. package/incident/05-cases/case-cascade-failure.md +176 -0
  317. package/incident/06-glossary/incident-glossary.md +114 -0
  318. package/incident/postmortem-and-response-deep-dive.md +39 -0
  319. package/industries/ecommerce/ecommerce-complete.md +631 -0
  320. package/industries/education/education-complete.md +555 -0
  321. package/industries/fintech/fintech-complete.md +501 -0
  322. package/industries/gaming/gaming-complete.md +587 -0
  323. package/industries/healthcare/healthcare-complete.md +452 -0
  324. package/low-code/01-standards/low-code-complete.md +944 -0
  325. package/miniprogram/01-standards/ai-common-mistakes.md +61 -0
  326. package/miniprogram/01-standards/miniprogram-custom-navbar-capsule.md +77 -0
  327. package/miniprogram/01-standards/miniprogram-design.md +61 -0
  328. package/miniprogram/01-standards/miniprogram-standard.md +81 -0
  329. package/mobile/01-standards/android-material-design.md +70 -0
  330. package/mobile/01-standards/flutter-complete.md +384 -0
  331. package/mobile/01-standards/ios-design-hig.md +78 -0
  332. package/mobile/01-standards/mobile-app-standard.md +85 -0
  333. package/mobile/01-standards/react-native-complete.md +352 -0
  334. package/mobile/02-playbooks/mobile-cross-platform-playbook.md +175 -0
  335. package/mobile/02-playbooks/mobile-performance.md +473 -0
  336. package/mobile/03-checklists/mobile-release-checklist.md +234 -0
  337. package/mobile/04-antipatterns/mobile-antipatterns.md +798 -0
  338. package/mobile/05-cases/case-app-performance.md +500 -0
  339. package/mobile/05-cases/case-app-startup-optimization.md +218 -0
  340. package/mobile/06-glossary/mobile-glossary.md +484 -0
  341. package/observability/01-standards/observability-standards.md +103 -0
  342. package/observability/02-playbooks/prometheus-grafana-playbook.md +135 -0
  343. package/observability/02-playbooks/structured-logging-playbook.md +73 -0
  344. package/observability/03-checklists/observability-checklist.md +54 -0
  345. package/observability/04-antipatterns/observability-antipatterns.md +106 -0
  346. package/operations/01-standards/prometheus-monitoring-complete.md +1578 -0
  347. package/operations/02-playbooks/capacity-planning-playbook.md +620 -0
  348. package/operations/03-checklists/production-launch-checklist.md +365 -0
  349. package/operations/04-antipatterns/operations-antipatterns.md +664 -0
  350. package/operations/05-cases/case-sre-practices.md +581 -0
  351. package/operations/06-glossary/operations-glossary.md +120 -0
  352. package/operations/aiops-anomaly-detection.md +758 -0
  353. package/operations/capacity-planning.md +1061 -0
  354. package/operations/chaos-engineering.md +659 -0
  355. package/operations/incident-command-system.md +38 -0
  356. package/operations/observability-complete.md +442 -0
  357. package/operations/slo-sli-playbook.md +517 -0
  358. package/operations/sre-operations-deep-dive.md +39 -0
  359. package/package.json +8 -0
  360. package/performance/01-standards/performance-and-scalability.md +80 -0
  361. package/performance/01-standards/performance-standards.md +156 -0
  362. package/performance/02-playbooks/query-optimization-playbook.md +103 -0
  363. package/performance/03-checklists/performance-checklist.md +56 -0
  364. package/performance/04-antipatterns/performance-antipatterns.md +146 -0
  365. package/product/01-standards/product-management-complete.md +285 -0
  366. package/product/02-playbooks/feature-launch-playbook.md +207 -0
  367. package/product/02-playbooks/user-research-playbook.md +532 -0
  368. package/product/03-checklists/feature-launch-checklist.md +275 -0
  369. package/product/04-antipatterns/product-antipatterns.md +355 -0
  370. package/product/05-cases/case-mvp-to-scale.md +384 -0
  371. package/product/06-glossary/product-glossary.md +462 -0
  372. package/product/feature-prioritization-framework.md +40 -0
  373. package/product/kpi-and-metric-tree.md +37 -0
  374. package/product/product-discovery-and-prd-deep-dive.md +41 -0
  375. package/quantum/01-standards/quantum-complete.md +1186 -0
  376. package/security/01-standards/api-security-complete.md +511 -0
  377. package/security/01-standards/container-runtime-security.md +574 -0
  378. package/security/01-standards/data-protection-gdpr.md +543 -0
  379. package/security/01-standards/owasp-top10-complete.md +1890 -0
  380. package/security/01-standards/secure-coding-baseline.md +90 -0
  381. package/security/01-standards/supply-chain-security.md +441 -0
  382. package/security/01-standards/web-security-checklist.md +108 -0
  383. package/security/01-standards/zero-trust-architecture.md +521 -0
  384. package/security/02-playbooks/auth-sso-playbook.md +166 -0
  385. package/security/02-playbooks/incident-response-security-playbook.md +588 -0
  386. package/security/02-playbooks/owasp-api-security-playbook.md +129 -0
  387. package/security/02-playbooks/payment-integration-playbook.md +119 -0
  388. package/security/02-playbooks/penetration-testing-playbook.md +517 -0
  389. package/security/03-checklists/security-audit-checklist.md +356 -0
  390. package/security/04-antipatterns/security-coding-antipatterns.md +580 -0
  391. package/security/05-cases/case-log4shell-incident.md +537 -0
  392. package/security/05-cases/case-major-breaches.md +468 -0
  393. package/security/06-glossary/security-glossary.md +212 -0
  394. package/security/compliance-automation.md +993 -0
  395. package/security/container-security.md +680 -0
  396. package/security/devsecops-complete.md +426 -0
  397. package/security/sast-dast-sca.md +775 -0
  398. package/security/secrets-management.md +594 -0
  399. package/security/security-architecture-deep-dive.md +37 -0
  400. package/security/threat-modeling-stride-playbook.md +40 -0
  401. package/seed-templates/auth-system.md +59 -0
  402. package/seed-templates/blog-content.md +94 -0
  403. package/seed-templates/dashboard.md +89 -0
  404. package/seed-templates/docs-site.md +73 -0
  405. package/seed-templates/e-commerce.md +50 -0
  406. package/seed-templates/saas-landing.md +92 -0
  407. package/seed-templates/settings-page.md +51 -0
  408. package/testing/01-standards/test-strategy-and-layering.md +83 -0
  409. package/testing/01-standards/testing-strategy-complete.md +422 -0
  410. package/testing/01-standards/unit-testing-best-practices.md +118 -0
  411. package/testing/02-playbooks/e2e-testing-playbook.md +988 -0
  412. package/testing/02-playbooks/testing-strategy-playbook.md +126 -0
  413. package/testing/03-checklists/test-strategy-checklist.md +208 -0
  414. package/testing/04-antipatterns/testing-antipatterns.md +718 -0
  415. package/testing/05-cases/case-testing-transformation.md +300 -0
  416. package/testing/06-glossary/testing-glossary.md +110 -0
  417. package/testing/risk-based-test-matrix.md +36 -0
  418. package/testing/testing-strategy-deep-dive.md +37 -0
@@ -0,0 +1,1220 @@
1
+ ---
2
+ id: distributed-transactions
3
+ title: 分布式事务处理完全指南
4
+ domain: architecture
5
+ category: distributed-transactions.md
6
+ difficulty: intermediate
7
+ tags: [architecture, distributed, transactions, 分布式事务框架, 分布式事务模式, 参考资源, 常见问题, 最佳实践]
8
+ quality_score: 70
9
+ last_updated: 2026-06-15
10
+ ---
11
+ # 分布式事务处理完全指南
12
+
13
+ ## 概述
14
+
15
+ 分布式事务是指跨越多个网络节点(服务、数据库)的事务操作,需要保证这些操作的原子性、一致性、隔离性和持久性(ACID)。在微服务架构中,由于每个服务拥有独立的数据库,传统的事务机制不再适用,需要采用专门的分布式事务解决方案。
16
+
17
+ ## 核心挑战
18
+
19
+ ### 1. ACID特性保障困难
20
+ ```
21
+ 原子性(Atomicity):
22
+ - 跨服务操作难以保证全部成功或全部失败
23
+ - 网络分区导致部分操作无法执行
24
+
25
+ 一致性(Consistency):
26
+ - 多个数据库间数据同步延迟
27
+ - 不同服务间的业务规则一致性
28
+
29
+ 隔离性(Isolation):
30
+ - 跨数据库的并发控制复杂
31
+ - 锁机制难以协调
32
+
33
+ 持久性(Durability):
34
+ - 多节点故障恢复
35
+ - 数据不一致的修复
36
+ ```
37
+
38
+ ### 2. CAP理论权衡
39
+ ```
40
+ Consistency(一致性): 强一致性 vs 最终一致性
41
+ Availability(可用性): 高可用 vs 数据准确
42
+ Partition Tolerance(分区容错): 网络分区时系统行为
43
+
44
+ 现实选择:
45
+ - 金融场景: CP(一致性优先)
46
+ - 社交场景: AP(可用性优先)
47
+ - 一般业务: 平衡AP和CP
48
+ ```
49
+
50
+ ### 3. 网络不确定性
51
+ ```
52
+ 超时:
53
+ - 请求发出后未收到响应
54
+ - 无法判断操作是否成功
55
+
56
+ 分区:
57
+ - 网络中断,节点间无法通信
58
+ - 脑裂问题
59
+
60
+ 延迟:
61
+ - 跨数据中心调用延迟高
62
+ - 影响事务响应时间
63
+ ```
64
+
65
+ ## 分布式事务模式
66
+
67
+ ### 1. 两阶段提交(2PC, Two-Phase Commit)
68
+
69
+ #### 工作原理
70
+ ```
71
+ 阶段一(准备阶段):
72
+ 1. 协调者向所有参与者发送准备请求
73
+ 2. 参与者执行本地事务,但不提交
74
+ 3. 参与者返回准备就绪或失败
75
+
76
+ 阶段二(提交阶段):
77
+ - 如果所有参与者都准备就绪:
78
+ 1. 协调者发送提交命令
79
+ 2. 参与者提交事务
80
+ 3. 返回提交成功
81
+
82
+ - 如果有参与者失败:
83
+ 1. 协调者发送回滚命令
84
+ 2. 参与者回滚事务
85
+ 3. 返回回滚成功
86
+ ```
87
+
88
+ #### 实现示例
89
+ ```java
90
+ // 协调者
91
+ public class TransactionCoordinator {
92
+ public boolean commitDistributedTransaction(List<Participant> participants) {
93
+ // 阶段一: 准备
94
+ boolean allPrepared = true;
95
+ for (Participant p : participants) {
96
+ if (!p.prepare()) {
97
+ allPrepared = false;
98
+ break;
99
+ }
100
+ }
101
+
102
+ // 阶段二: 提交或回滚
103
+ if (allPrepared) {
104
+ for (Participant p : participants) {
105
+ p.commit();
106
+ }
107
+ return true;
108
+ } else {
109
+ for (Participant p : participants) {
110
+ p.rollback();
111
+ }
112
+ return false;
113
+ }
114
+ }
115
+ }
116
+
117
+ // 参与者
118
+ public class Participant {
119
+ public boolean prepare() {
120
+ try {
121
+ // 执行本地事务,不提交
122
+ connection.setAutoCommit(false);
123
+ executeLocalTransaction();
124
+ return true;
125
+ } catch (Exception e) {
126
+ return false;
127
+ }
128
+ }
129
+
130
+ public void commit() {
131
+ connection.commit();
132
+ }
133
+
134
+ public void rollback() {
135
+ connection.rollback();
136
+ }
137
+ }
138
+ ```
139
+
140
+ #### 优缺点
141
+ ```
142
+ 优点:
143
+ - 强一致性保证
144
+ - 数据不丢失
145
+ - 逻辑清晰
146
+
147
+ 缺点:
148
+ - 同步阻塞: 参与者锁定资源等待
149
+ - 单点故障: 协调者故障导致系统阻塞
150
+ - 数据不一致: 阶段二部分提交失败
151
+ - 性能差: 网络往返次数多
152
+
153
+ 适用场景:
154
+ - 对一致性要求极高
155
+ - 参与者数量少
156
+ - 网络稳定的环境
157
+ ```
158
+
159
+ ### 2. 三阶段提交(3PC, Three-Phase Commit)
160
+
161
+ #### 改进点
162
+ ```
163
+ 引入CanCommit阶段:
164
+ 1. CanCommit: 询问是否可以执行事务
165
+ 2. PreCommit: 执行事务,准备提交
166
+ 3. DoCommit: 正式提交
167
+
168
+ 超时机制:
169
+ - 参与者超时后自动提交或回滚
170
+ - 减少阻塞时间
171
+ ```
172
+
173
+ #### 优缺点
174
+ ```
175
+ 优点:
176
+ - 减少阻塞范围
177
+ - 引入超时机制
178
+
179
+ 缺点:
180
+ - 仍可能数据不一致
181
+ - 网络往返次数更多
182
+ - 实现复杂
183
+
184
+ 适用场景:
185
+ - 对2PC的改进方案
186
+ - 要求降低阻塞时间
187
+ ```
188
+
189
+ ### 3. TCC(Try-Confirm-Cancel)
190
+
191
+ #### 工作原理
192
+ ```
193
+ Try阶段:
194
+ - 资源预留和锁定
195
+ - 业务检查
196
+ - 不执行真正业务
197
+
198
+ Confirm阶段:
199
+ - 确认执行业务操作
200
+ - 使用Try阶段预留的资源
201
+ - 不做业务检查
202
+
203
+ Cancel阶段:
204
+ - 取消业务操作
205
+ - 释放Try阶段预留的资源
206
+ ```
207
+
208
+ #### 实现示例
209
+ ```java
210
+ // 转账服务
211
+ public class TransferService {
212
+ // Try: 冻结转账金额
213
+ public boolean tryTransfer(String fromAccount, String toAccount, BigDecimal amount) {
214
+ Account from = accountRepository.findByAccountNumber(fromAccount);
215
+ if (from.getBalance().compareTo(amount) < 0) {
216
+ return false;
217
+ }
218
+
219
+ // 冻结金额
220
+ from.setFrozenAmount(from.getFrozenAmount().add(amount));
221
+ from.setBalance(from.getBalance().subtract(amount));
222
+ accountRepository.save(from);
223
+
224
+ return true;
225
+ }
226
+
227
+ // Confirm: 确认转账
228
+ public void confirmTransfer(String fromAccount, String toAccount, BigDecimal amount) {
229
+ Account from = accountRepository.findByAccountNumber(fromAccount);
230
+ Account to = accountRepository.findByAccountNumber(toAccount);
231
+
232
+ // 清除冻结
233
+ from.setFrozenAmount(from.getFrozenAmount().subtract(amount));
234
+
235
+ // 入账
236
+ to.setBalance(to.getBalance().add(amount));
237
+
238
+ accountRepository.save(from);
239
+ accountRepository.save(to);
240
+ }
241
+
242
+ // Cancel: 取消转账
243
+ public void cancelTransfer(String fromAccount, String toAccount, BigDecimal amount) {
244
+ Account from = accountRepository.findByAccountNumber(fromAccount);
245
+
246
+ // 释放冻结,恢复余额
247
+ from.setFrozenAmount(from.getFrozenAmount().subtract(amount));
248
+ from.setBalance(from.getBalance().add(amount));
249
+
250
+ accountRepository.save(from);
251
+ }
252
+ }
253
+
254
+ // TCC事务协调器
255
+ public class TccTransactionCoordinator {
256
+ public void executeTransfer(String from, String to, BigDecimal amount) {
257
+ try {
258
+ // Try
259
+ if (!transferService.tryTransfer(from, to, amount)) {
260
+ throw new RuntimeException("Try阶段失败");
261
+ }
262
+
263
+ // Confirm
264
+ transferService.confirmTransfer(from, to, amount);
265
+
266
+ } catch (Exception e) {
267
+ // Cancel
268
+ transferService.cancelTransfer(from, to, amount);
269
+ throw e;
270
+ }
271
+ }
272
+ }
273
+ ```
274
+
275
+ #### 数据库设计
276
+ ```sql
277
+ -- 账户表
278
+ CREATE TABLE account (
279
+ id BIGINT PRIMARY KEY,
280
+ account_number VARCHAR(32) UNIQUE NOT NULL,
281
+ balance DECIMAL(19,2) NOT NULL,
282
+ frozen_amount DECIMAL(19,2) DEFAULT 0,
283
+ version INT DEFAULT 0,
284
+ INDEX idx_account_number (account_number)
285
+ );
286
+
287
+ -- TCC事务日志
288
+ CREATE TABLE tcc_transaction_log (
289
+ id BIGINT PRIMARY KEY AUTO_INCREMENT,
290
+ transaction_id VARCHAR(64) NOT NULL,
291
+ branch_id VARCHAR(64) NOT NULL,
292
+ status VARCHAR(20) NOT NULL, -- TRY, CONFIRM, CANCEL
293
+ business_key VARCHAR(128),
294
+ context TEXT,
295
+ create_time TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
296
+ update_time TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
297
+ INDEX idx_transaction (transaction_id),
298
+ INDEX idx_status (status)
299
+ );
300
+ ```
301
+
302
+ #### 优缺点
303
+ ```
304
+ 优点:
305
+ - 最终一致性
306
+ - 锁粒度小,性能好
307
+ - 灵活性高,业务可控
308
+
309
+ 缺点:
310
+ - 业务侵入性强
311
+ - 实现复杂,需要三个接口
312
+ - 需要幂等性处理
313
+ - 需要防悬挂(空回滚)
314
+
315
+ 适用场景:
316
+ - 金融转账
317
+ - 库存预占
318
+ - 优惠券发放
319
+ ```
320
+
321
+ #### 关键问题解决
322
+
323
+ ##### 幂等性
324
+ ```java
325
+ public boolean tryTransfer(String transactionId, String from, String to, BigDecimal amount) {
326
+ // 检查是否已执行
327
+ TccTransactionLog log = logRepository.findByTransactionId(transactionId);
328
+ if (log != null && "TRY".equals(log.getStatus())) {
329
+ return true; // 已执行,直接返回成功
330
+ }
331
+
332
+ // 执行业务
333
+ // ...
334
+
335
+ // 记录日志
336
+ logRepository.save(new TccTransactionLog(transactionId, "TRY"));
337
+ return true;
338
+ }
339
+ ```
340
+
341
+ ##### 防悬挂
342
+ ```java
343
+ public void cancelTransfer(String transactionId, String from, String to, BigDecimal amount) {
344
+ // 检查Try是否已执行
345
+ TccTransactionLog log = logRepository.findByTransactionId(transactionId);
346
+ if (log == null) {
347
+ // Try未执行,记录Cancel日志防止悬挂
348
+ logRepository.save(new TccTransactionLog(transactionId, "CANCEL"));
349
+ return;
350
+ }
351
+
352
+ // 执行Cancel逻辑
353
+ // ...
354
+ }
355
+ ```
356
+
357
+ ### 4. Saga模式
358
+
359
+ #### 编排式Saga(Choreography)
360
+
361
+ ##### 工作原理
362
+ ```
363
+ 1. 每个服务执行本地事务
364
+ 2. 发布事件通知其他服务
365
+ 3. 其他服务监听事件并执行相应操作
366
+ 4. 如果某步骤失败,执行补偿事务
367
+ ```
368
+
369
+ ##### 实现示例
370
+ ```java
371
+ // 订单服务
372
+ @Service
373
+ public class OrderService {
374
+ @Transactional
375
+ public Order createOrder(OrderRequest request) {
376
+ // 1. 创建订单(待确认状态)
377
+ Order order = new Order();
378
+ order.setStatus("CREATED");
379
+ orderRepository.save(order);
380
+
381
+ // 2. 发布订单创建事件
382
+ eventPublisher.publish(new OrderCreatedEvent(order.getId(), request));
383
+
384
+ return order;
385
+ }
386
+
387
+ @Transactional
388
+ @EventListener
389
+ public void handlePaymentFailed(PaymentFailedEvent event) {
390
+ // 补偿: 取消订单
391
+ Order order = orderRepository.findById(event.getOrderId());
392
+ order.setStatus("CANCELLED");
393
+ orderRepository.save(order);
394
+
395
+ // 发布订单取消事件
396
+ eventPublisher.publish(new OrderCancelledEvent(order.getId()));
397
+ }
398
+ }
399
+
400
+ // 支付服务
401
+ @Service
402
+ public class PaymentService {
403
+ @Transactional
404
+ @EventListener
405
+ public void handleOrderCreated(OrderCreatedEvent event) {
406
+ try {
407
+ // 执行支付
408
+ Payment payment = paymentService.process(event.getPaymentRequest());
409
+
410
+ // 发布支付成功事件
411
+ eventPublisher.publish(new PaymentSuccessEvent(event.getOrderId(), payment.getId()));
412
+
413
+ } catch (Exception e) {
414
+ // 发布支付失败事件
415
+ eventPublisher.publish(new PaymentFailedEvent(event.getOrderId()));
416
+ }
417
+ }
418
+ }
419
+
420
+ // 库存服务
421
+ @Service
422
+ public class InventoryService {
423
+ @Transactional
424
+ @EventListener
425
+ public void handlePaymentSuccess(PaymentSuccessEvent event) {
426
+ // 扣减库存
427
+ inventoryService.deduct(event.getProductId(), event.getQuantity());
428
+
429
+ // 发布库存扣减成功事件
430
+ eventPublisher.publish(new InventoryDeductedEvent(event.getOrderId()));
431
+ }
432
+
433
+ @Transactional
434
+ @EventListener
435
+ public void handleOrderCancelled(OrderCancelledEvent event) {
436
+ // 补偿: 恢复库存
437
+ inventoryService.restore(event.getProductId(), event.getQuantity());
438
+ }
439
+ }
440
+ ```
441
+
442
+ ##### 优缺点
443
+ ```
444
+ 优点:
445
+ - 简单,无中心协调器
446
+ - 服务间松耦合
447
+ - 易于扩展
448
+
449
+ 缺点:
450
+ - 流程不清晰,难以理解
451
+ - 事件循环依赖风险
452
+ - 调试困难
453
+ - 补偿逻辑分散
454
+
455
+ 适用场景:
456
+ - 简单业务流程
457
+ - 服务数量少
458
+ - 团队自治度高
459
+ ```
460
+
461
+ #### 编制式Saga(Orchestration)
462
+
463
+ ##### 工作原理
464
+ ```
465
+ 1. 中央协调器(Saga Orchestrator)管理整个流程
466
+ 2. 协调器按顺序调用各个服务
467
+ 3. 服务执行成功,继续下一步
468
+ 4. 服务执行失败,协调器执行补偿操作
469
+ ```
470
+
471
+ ##### 实现示例
472
+ ```java
473
+ // Saga定义
474
+ public class CreateOrderSaga {
475
+ private List<SagaStep> steps;
476
+
477
+ public CreateOrderSaga() {
478
+ steps = Arrays.asList(
479
+ new CreateOrderStep(),
480
+ new ReserveInventoryStep(),
481
+ new ProcessPaymentStep(),
482
+ new ConfirmOrderStep()
483
+ );
484
+ }
485
+
486
+ public void execute(OrderContext context) {
487
+ int currentStep = 0;
488
+
489
+ try {
490
+ // 正向执行
491
+ for (; currentStep < steps.size(); currentStep++) {
492
+ steps.get(currentStep).execute(context);
493
+ }
494
+ } catch (Exception e) {
495
+ // 补偿执行(回滚已执行的步骤)
496
+ for (int i = currentStep - 1; i >= 0; i--) {
497
+ steps.get(i).compensate(context);
498
+ }
499
+ throw e;
500
+ }
501
+ }
502
+ }
503
+
504
+ // Saga步骤接口
505
+ public interface SagaStep {
506
+ void execute(OrderContext context);
507
+ void compensate(OrderContext context);
508
+ }
509
+
510
+ // 库存预留步骤
511
+ public class ReserveInventoryStep implements SagaStep {
512
+ @Override
513
+ public void execute(OrderContext context) {
514
+ InventoryService inventoryService = context.getInventoryService();
515
+ boolean success = inventoryService.reserve(
516
+ context.getProductId(),
517
+ context.getQuantity()
518
+ );
519
+
520
+ if (!success) {
521
+ throw new RuntimeException("库存不足");
522
+ }
523
+
524
+ context.setInventoryReserved(true);
525
+ }
526
+
527
+ @Override
528
+ public void compensate(OrderContext context) {
529
+ if (context.isInventoryReserved()) {
530
+ InventoryService inventoryService = context.getInventoryService();
531
+ inventoryService.release(
532
+ context.getProductId(),
533
+ context.getQuantity()
534
+ );
535
+ }
536
+ }
537
+ }
538
+
539
+ // Saga协调器
540
+ @Service
541
+ public class SagaOrchestrator {
542
+ @Autowired
543
+ private SagaInstanceRepository sagaRepository;
544
+
545
+ public void startSaga(String sagaType, Object payload) {
546
+ // 创建Saga实例
547
+ SagaInstance instance = new SagaInstance();
548
+ instance.setSagaType(sagaType);
549
+ instance.setPayload(JsonUtil.toJson(payload));
550
+ instance.setStatus("RUNNING");
551
+ sagaRepository.save(instance);
552
+
553
+ // 执行Saga
554
+ try {
555
+ Saga saga = sagaFactory.createSaga(sagaType);
556
+ saga.execute(payload);
557
+
558
+ instance.setStatus("COMPLETED");
559
+ } catch (Exception e) {
560
+ instance.setStatus("FAILED");
561
+ instance.setError(e.getMessage());
562
+ }
563
+
564
+ sagaRepository.save(instance);
565
+ }
566
+ }
567
+ ```
568
+
569
+ ##### Saga状态机
570
+ ```java
571
+ public enum SagaState {
572
+ STARTED,
573
+ ORDER_CREATED,
574
+ INVENTORY_RESERVED,
575
+ PAYMENT_PROCESSED,
576
+ ORDER_CONFIRMED,
577
+ COMPLETED,
578
+ COMPENSATING,
579
+ COMPENSATED
580
+ }
581
+
582
+ public class SagaStateMachine {
583
+ private SagaState currentState;
584
+
585
+ public void transition(SagaEvent event) {
586
+ switch (currentState) {
587
+ case STARTED:
588
+ if (event == SagaEvent.ORDER_CREATED_SUCCESS) {
589
+ currentState = SagaState.ORDER_CREATED;
590
+ } else if (event == SagaEvent.ORDER_CREATED_FAIL) {
591
+ currentState = SagaState.COMPENSATED;
592
+ }
593
+ break;
594
+
595
+ case ORDER_CREATED:
596
+ if (event == SagaEvent.INVENTORY_RESERVED_SUCCESS) {
597
+ currentState = SagaState.INVENTORY_RESERVED;
598
+ } else if (event == SagaEvent.INVENTORY_RESERVED_FAIL) {
599
+ currentState = SagaState.COMPENSATING;
600
+ }
601
+ break;
602
+
603
+ // ... 其他状态转换
604
+
605
+ case COMPENSATING:
606
+ if (event == SagaEvent.COMPENSATION_COMPLETE) {
607
+ currentState = SagaState.COMPENSATED;
608
+ }
609
+ break;
610
+ }
611
+ }
612
+ }
613
+ ```
614
+
615
+ ##### 数据库设计
616
+ ```sql
617
+ -- Saga实例表
618
+ CREATE TABLE saga_instance (
619
+ id BIGINT PRIMARY KEY AUTO_INCREMENT,
620
+ saga_id VARCHAR(64) UNIQUE NOT NULL,
621
+ saga_type VARCHAR(128) NOT NULL,
622
+ status VARCHAR(20) NOT NULL, -- RUNNING, COMPLETED, FAILED, COMPENSATING
623
+ payload TEXT,
624
+ current_step INT DEFAULT 0,
625
+ error_message TEXT,
626
+ create_time TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
627
+ update_time TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
628
+ INDEX idx_saga_id (saga_id),
629
+ INDEX idx_status (status)
630
+ );
631
+
632
+ -- Saga步骤执行日志
633
+ CREATE TABLE saga_step_log (
634
+ id BIGINT PRIMARY KEY AUTO_INCREMENT,
635
+ saga_id VARCHAR(64) NOT NULL,
636
+ step_name VARCHAR(128) NOT NULL,
637
+ step_type VARCHAR(20) NOT NULL, -- FORWARD, COMPENSATION
638
+ status VARCHAR(20) NOT NULL, -- SUCCESS, FAILED
639
+ input_data TEXT,
640
+ output_data TEXT,
641
+ error_message TEXT,
642
+ execution_time TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
643
+ INDEX idx_saga_id (saga_id)
644
+ );
645
+ ```
646
+
647
+ ##### 优缺点
648
+ ```
649
+ 优点:
650
+ - 流程清晰,易于理解
651
+ - 集中管理,便于监控
652
+ - 补偿逻辑统一
653
+ - 支持复杂流程
654
+
655
+ 缺点:
656
+ - 协调器单点故障
657
+ - 协调器逻辑复杂
658
+ - 服务与协调器耦合
659
+
660
+ 适用场景:
661
+ - 复杂业务流程
662
+ - 需要集中管理的事务
663
+ - 企业级应用
664
+ ```
665
+
666
+ ### 5. 本地消息表(本地事件表)
667
+
668
+ #### 工作原理
669
+ ```
670
+ 1. 业务操作和消息记录在同一个本地事务中
671
+ 2. 后台任务定期扫描未发送的消息
672
+ 3. 发送消息到消息队列
673
+ 4. 消费者处理消息,确保幂等性
674
+ 5. 生产者收到确认后标记消息已发送
675
+ ```
676
+
677
+ #### 实现示例
678
+ ```java
679
+ // 生产者
680
+ @Service
681
+ public class OrderService {
682
+ @Transactional
683
+ public void createOrder(Order order) {
684
+ // 1. 插入订单
685
+ orderRepository.insert(order);
686
+
687
+ // 2. 插入本地消息(同一事务)
688
+ LocalMessage message = new LocalMessage();
689
+ message.setMessageId(UUID.randomUUID().toString());
690
+ message.setTopic("order-created");
691
+ message.setPayload(JsonUtil.toJson(order));
692
+ message.setStatus("PENDING");
693
+ localMessageRepository.insert(message);
694
+ }
695
+ }
696
+
697
+ // 消息发送任务
698
+ @Component
699
+ public class MessageSender {
700
+ @Scheduled(fixedDelay = 1000)
701
+ public void sendPendingMessages() {
702
+ // 查询待发送消息
703
+ List<LocalMessage> messages = localMessageRepository.findByStatus("PENDING");
704
+
705
+ for (LocalMessage message : messages) {
706
+ try {
707
+ // 发送到消息队列
708
+ mqProducer.send(message.getTopic(), message.getPayload());
709
+
710
+ // 更新状态为已发送
711
+ localMessageRepository.updateStatus(
712
+ message.getMessageId(),
713
+ "SENT"
714
+ );
715
+ } catch (Exception e) {
716
+ log.error("发送消息失败: {}", message.getMessageId(), e);
717
+ }
718
+ }
719
+ }
720
+ }
721
+
722
+ // 消费者
723
+ @Service
724
+ public class InventoryService {
725
+ @RabbitListener(queues = "order-created")
726
+ @Transactional
727
+ public void handleOrderCreated(String message) {
728
+ Order order = JsonUtil.fromJson(message, Order.class);
729
+
730
+ // 幂等性检查
731
+ if (processedMessageRepository.exists(order.getId())) {
732
+ return; // 已处理,跳过
733
+ }
734
+
735
+ // 业务处理
736
+ inventoryService.deduct(order.getProductId(), order.getQuantity());
737
+
738
+ // 记录已处理的消息
739
+ processedMessageRepository.insert(order.getId());
740
+ }
741
+ }
742
+ ```
743
+
744
+ #### 数据库设计
745
+ ```sql
746
+ -- 本地消息表
747
+ CREATE TABLE local_message (
748
+ id BIGINT PRIMARY KEY AUTO_INCREMENT,
749
+ message_id VARCHAR(64) UNIQUE NOT NULL,
750
+ topic VARCHAR(128) NOT NULL,
751
+ payload TEXT NOT NULL,
752
+ status VARCHAR(20) NOT NULL, -- PENDING, SENT, FAILED
753
+ retry_count INT DEFAULT 0,
754
+ next_retry_time TIMESTAMP,
755
+ create_time TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
756
+ update_time TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
757
+ INDEX idx_status (status),
758
+ INDEX idx_next_retry (next_retry_time)
759
+ );
760
+
761
+ -- 已处理消息表(消费者端)
762
+ CREATE TABLE processed_message (
763
+ id BIGINT PRIMARY KEY AUTO_INCREMENT,
764
+ message_id VARCHAR(64) UNIQUE NOT NULL,
765
+ consumer_group VARCHAR(128) NOT NULL,
766
+ process_time TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
767
+ INDEX idx_message (message_id, consumer_group)
768
+ );
769
+ ```
770
+
771
+ #### 优缺点
772
+ ```
773
+ 优点:
774
+ - 最终一致性保证
775
+ - 实现简单
776
+ - 不依赖复杂的框架
777
+ - 容易理解和维护
778
+
779
+ 缺点:
780
+ - 消息延迟(定时任务扫描)
781
+ - 消息表需要定期清理
782
+ - 数据库压力
783
+
784
+ 适用场景:
785
+ - 对实时性要求不高
786
+ - 需要可靠消息传递
787
+ - 中小型系统
788
+ ```
789
+
790
+ ### 6. 事务消息(RocketMQ)
791
+
792
+ #### 工作原理
793
+ ```
794
+ 1. 发送半消息(Half Message,不可消费)
795
+ 2. 执行本地事务
796
+ 3. 提交或回滚消息
797
+ - 提交: 消息变为可消费
798
+ - 回滚: 删除消息
799
+ 4. 如果未收到提交/回滚,MQ回查事务状态
800
+ ```
801
+
802
+ #### 实现示例
803
+ ```java
804
+ // 生产者
805
+ @Service
806
+ public class OrderService {
807
+ @Autowired
808
+ private RocketMQTemplate rocketMQTemplate;
809
+
810
+ public void createOrder(Order order) {
811
+ // 构建消息
812
+ Message<Order> message = MessageBuilder.withPayload(order).build();
813
+
814
+ // 发送事务消息
815
+ rocketMQTemplate.sendMessageInTransaction(
816
+ "order-group",
817
+ "order-created",
818
+ message,
819
+ order
820
+ );
821
+ }
822
+ }
823
+
824
+ // 事务监听器
825
+ @RocketMQTransactionListener(rocketMQTemplateBeanName = "rocketMQTemplate")
826
+ public class OrderTransactionListener implements RocketMQLocalTransactionListener {
827
+ @Override
828
+ @Transactional
829
+ public RocketMQLocalTransactionState executeLocalTransaction(Message msg, Object arg) {
830
+ try {
831
+ Order order = (Order) arg;
832
+
833
+ // 执行本地事务
834
+ orderRepository.insert(order);
835
+
836
+ // 返回提交状态
837
+ return RocketMQLocalTransactionState.COMMIT;
838
+
839
+ } catch (Exception e) {
840
+ // 返回回滚状态
841
+ return RocketMQLocalTransactionState.ROLLBACK;
842
+ }
843
+ }
844
+
845
+ @Override
846
+ public RocketMQLocalTransactionState checkLocalTransaction(Message msg) {
847
+ // 回查本地事务状态
848
+ Order order = JsonUtil.fromJson(
849
+ new String((byte[]) msg.getPayload()),
850
+ Order.class
851
+ );
852
+
853
+ if (orderRepository.exists(order.getId())) {
854
+ return RocketMQLocalTransactionState.COMMIT;
855
+ } else {
856
+ return RocketMQLocalTransactionState.ROLLBACK;
857
+ }
858
+ }
859
+ }
860
+
861
+ // 消费者
862
+ @Service
863
+ @RocketMQMessageListener(
864
+ topic = "order-created",
865
+ consumerGroup = "inventory-group"
866
+ )
867
+ public class InventoryConsumer implements RocketMQListener<Order> {
868
+ @Override
869
+ @Transactional
870
+ public void onMessage(Order order) {
871
+ // 幂等性检查
872
+ if (processedOrderRepository.exists(order.getId())) {
873
+ return;
874
+ }
875
+
876
+ // 扣减库存
877
+ inventoryService.deduct(order.getProductId(), order.getQuantity());
878
+
879
+ // 记录已处理
880
+ processedOrderRepository.insert(order.getId());
881
+ }
882
+ }
883
+ ```
884
+
885
+ #### 优缺点
886
+ ```
887
+ 优点:
888
+ - 最终一致性
889
+ - 消息零丢失
890
+ - 实时性高
891
+ - 解耦业务与消息
892
+
893
+ 缺点:
894
+ - 依赖特定MQ(RocketMQ)
895
+ - 实现相对复杂
896
+ - 需要回查接口
897
+
898
+ 适用场景:
899
+ - 高可靠消息传递
900
+ - 订单、支付等核心业务
901
+ - 使用RocketMQ的系统
902
+ ```
903
+
904
+ ## 分布式事务框架
905
+
906
+ ### 1. Seata
907
+
908
+ #### 架构
909
+ ```
910
+ TC (Transaction Coordinator): 事务协调器
911
+ TM (Transaction Manager): 事务管理器
912
+ RM (Resource Manager): 资源管理器
913
+
914
+ 工作流程:
915
+ 1. TM向TC申请开启全局事务
916
+ 2. TC返回全局事务ID(XID)
917
+ 3. RM向TC注册分支事务
918
+ 4. TM通知TC提交/回滚全局事务
919
+ 5. TC协调所有分支事务提交/回滚
920
+ ```
921
+
922
+ #### AT模式
923
+ ```java
924
+ // 开启全局事务
925
+ @GlobalTransactional
926
+ public void createOrder(OrderRequest request) {
927
+ // 1. 创建订单
928
+ orderService.createOrder(request);
929
+
930
+ // 2. 扣减库存
931
+ inventoryService.deduct(request.getProductId(), request.getQuantity());
932
+
933
+ // 3. 扣减余额
934
+ accountService.debit(request.getUserId(), request.getAmount());
935
+ }
936
+
937
+ // 配置
938
+ @SpringBootApplication
939
+ @EnableAutoDataSourceProxy
940
+ public class Application {
941
+ public static void main(String[] args) {
942
+ SpringApplication.run(Application.class, args);
943
+ }
944
+ }
945
+ ```
946
+
947
+ ```
948
+ 优点:
949
+ - 无侵入,自动补偿
950
+ - 使用简单
951
+ - 性能好
952
+
953
+ 缺点:
954
+ - 需要数据库支持
955
+ - 存在脏回滚风险
956
+ - 全局锁可能影响并发
957
+
958
+ 适用场景:
959
+ - 大多数业务场景
960
+ - Java应用
961
+ - 快速迁移
962
+ ```
963
+
964
+ #### TCC模式
965
+ ```java
966
+ @LocalTCC
967
+ public interface InventoryService {
968
+ @TwoPhaseBusinessAction(
969
+ name = "prepareDeduct",
970
+ commitMethod = "commit",
971
+ rollbackMethod = "rollback"
972
+ )
973
+ boolean prepareDeduct(
974
+ @BusinessActionContextParameter(paramName = "productId") String productId,
975
+ @BusinessActionContextParameter(paramName = "count") int count
976
+ );
977
+
978
+ boolean commit(BusinessActionContext context);
979
+
980
+ boolean rollback(BusinessActionContext context);
981
+ }
982
+
983
+ // 使用
984
+ @GlobalTransactional
985
+ public void placeOrder(String productId, int count) {
986
+ inventoryService.prepareDeduct(productId, count);
987
+ // ...
988
+ }
989
+ ```
990
+
991
+ #### Saga模式
992
+ ```yaml
993
+ # saga定义
994
+ type: "saga"
995
+ name: "create-order-saga"
996
+ steps:
997
+ - name: "create-order"
998
+ service: "order-service"
999
+ transaction:
1000
+ path: "/orders"
1001
+ method: "POST"
1002
+ compensation:
1003
+ path: "/orders/{orderId}"
1004
+ method: "DELETE"
1005
+
1006
+ - name: "reserve-inventory"
1007
+ service: "inventory-service"
1008
+ transaction:
1009
+ path: "/inventory/reserve"
1010
+ method: "POST"
1011
+ compensation:
1012
+ path: "/inventory/release"
1013
+ method: "POST"
1014
+
1015
+ - name: "process-payment"
1016
+ service: "payment-service"
1017
+ transaction:
1018
+ path: "/payments"
1019
+ method: "POST"
1020
+ compensation:
1021
+ path: "/payments/{paymentId}/refund"
1022
+ method: "POST"
1023
+ ```
1024
+
1025
+ ### 2. DTM
1026
+
1027
+ #### 特点
1028
+ ```
1029
+ - 跨语言支持(Go, Java, Python, PHP等)
1030
+ - 支持多种模式(Saga, TCC, 2PC)
1031
+ - 轻量级,易部署
1032
+ - HTTP/gRPC协议
1033
+ ```
1034
+
1035
+ #### Saga示例
1036
+ ```go
1037
+ // Go示例
1038
+ func main() {
1039
+ // 创建Saga
1040
+ saga := dtmcli.NewSaga("http://localhost:36789/api/dtmsvr", "").
1041
+ Add("http://localhost:8080/order/create", "http://localhost:8080/order/cancel", &OrderReq{}).
1042
+ Add("http://localhost:8080/inventory/deduct", "http://localhost:8080/inventory/restore", &InventoryReq{}).
1043
+ Add("http://localhost:8080/payment/process", "http://localhost:8080/payment/refund", &PaymentReq{})
1044
+
1045
+ // 提交Saga
1046
+ err := saga.Submit()
1047
+ if err != nil {
1048
+ panic(err)
1049
+ }
1050
+ }
1051
+ ```
1052
+
1053
+ ## 选型建议
1054
+
1055
+ ### 场景对比
1056
+
1057
+ ```
1058
+ 强一致性要求:
1059
+ - 2PC/3PC
1060
+ - Seata AT模式
1061
+ 适用: 金融核心、账户余额
1062
+
1063
+ 最终一致性:
1064
+ - TCC
1065
+ - Saga
1066
+ - 本地消息表
1067
+ - 事务消息
1068
+ 适用: 电商订单、库存、积分
1069
+
1070
+ 简单场景:
1071
+ - 本地消息表
1072
+ 适用: 非核心业务,流量小
1073
+
1074
+ 复杂业务流程:
1075
+ - Saga编制式
1076
+ 适用: 多步骤,有补偿逻辑
1077
+
1078
+ 高性能:
1079
+ - TCC
1080
+ - Saga
1081
+ 适用: 高并发,短事务
1082
+ ```
1083
+
1084
+ ### 技术栈匹配
1085
+
1086
+ ```
1087
+ Java生态:
1088
+ - Seata(AT/TCC/Saga)
1089
+ - RocketMQ事务消息
1090
+ - 本地消息表
1091
+
1092
+ Go生态:
1093
+ - DTM
1094
+ - 本地消息表
1095
+
1096
+ 混合技术栈:
1097
+ - DTM(跨语言)
1098
+ - HTTP API + 消息队列
1099
+ ```
1100
+
1101
+ ## 最佳实践
1102
+
1103
+ ### 1. 幂等性设计
1104
+ ```
1105
+ 唯一ID:
1106
+ - 业务唯一键(订单号)
1107
+ - 幂等令牌(Idempotency Key)
1108
+
1109
+ 实现:
1110
+ - 数据库唯一索引
1111
+ - Redis SETNX
1112
+ - 状态机检查
1113
+ ```
1114
+
1115
+ ### 2. 补偿事务设计
1116
+ ```
1117
+ 原则:
1118
+ - 补偿操作必须成功
1119
+ - 补偿操作可重试
1120
+ - 补偿操作幂等
1121
+
1122
+ 实现:
1123
+ - 补偿失败记录日志
1124
+ - 人工干预机制
1125
+ - 定期重试补偿
1126
+ ```
1127
+
1128
+ ### 3. 事务隔离
1129
+ ```
1130
+ 读已提交:
1131
+ - 大多数场景适用
1132
+
1133
+ 串行化:
1134
+ - 金融核心业务
1135
+ - 需要防止脏读、不可重复读
1136
+
1137
+ 实现:
1138
+ - 数据库隔离级别
1139
+ - 分布式锁
1140
+ ```
1141
+
1142
+ ### 4. 超时与重试
1143
+ ```
1144
+ 超时设置:
1145
+ - 根据业务RT设置合理超时
1146
+ - 避免过长导致资源占用
1147
+
1148
+ 重试策略:
1149
+ - 指数退避
1150
+ - 最大重试次数
1151
+ - 死信队列
1152
+ ```
1153
+
1154
+ ### 5. 监控与告警
1155
+ ```
1156
+ 监控指标:
1157
+ - 事务成功率
1158
+ - 事务耗时(P99)
1159
+ - 补偿次数
1160
+ - 失败原因分布
1161
+
1162
+ 告警:
1163
+ - 事务失败率超过阈值
1164
+ - 补偿失败
1165
+ - 长时间未完成的事务
1166
+ ```
1167
+
1168
+ ## 常见问题
1169
+
1170
+ ### 1. 事务超时
1171
+ ```
1172
+ 原因:
1173
+ - 网络延迟
1174
+ - 服务响应慢
1175
+ - 数据库锁等待
1176
+
1177
+ 解决:
1178
+ - 设置合理超时时间
1179
+ - 优化慢查询
1180
+ - 使用异步处理
1181
+ ```
1182
+
1183
+ ### 2. 数据不一致
1184
+ ```
1185
+ 原因:
1186
+ - 补偿失败
1187
+ - 并发冲突
1188
+ - 网络分区
1189
+
1190
+ 解决:
1191
+ - 补偿重试机制
1192
+ - 对账脚本
1193
+ - 人工修复工具
1194
+ ```
1195
+
1196
+ ### 3. 性能问题
1197
+ ```
1198
+ 原因:
1199
+ - 全局锁竞争
1200
+ - 长事务
1201
+ - 同步调用链长
1202
+
1203
+ 解决:
1204
+ - 缩短事务范围
1205
+ - 异步化处理
1206
+ - 优化热点数据
1207
+ ```
1208
+
1209
+ ## 参考资源
1210
+
1211
+ ### 开源框架
1212
+ - Seata: https://seata.io/
1213
+ - DTM: https://en.dtm.pub/
1214
+ - RocketMQ: https://rocketmq.apache.org/
1215
+
1216
+ ### 学习资料
1217
+ - 《分布式系统原理》
1218
+ - 《微服务架构设计模式》
1219
+ - Martin Fowler: Sagas论文
1220
+ - Google Spanner论文