From 6e13832d979e895154f3be232bea527474b69a6a Mon Sep 17 00:00:00 2001 From: sanbuphy Date: Mon, 23 Feb 2026 12:09:47 +0800 Subject: [PATCH] =?UTF-8?q?feat:=20=E6=9B=B4=E6=96=B0=E9=99=84=E5=BD=95?= =?UTF-8?q?=E6=96=87=E6=A1=A3=E5=8F=8A=E5=AF=B9=E5=BA=94=E4=BA=A4=E4=BA=92?= =?UTF-8?q?=E7=BB=84=E4=BB=B6?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../appendix/api-intro/ApiConceptDemo.vue | 6 +- .../appendix/api-intro/ApiDocumentDemo.vue | 9 +- .../appendix/api-intro/ApiMethodDemo.vue | 6 +- .../appendix/api-intro/ApiPlayground.vue | 105 +- .../appendix/api-intro/ApiQuickStartDemo.vue | 6 +- .../appendix/api-intro/ApiTypesComparison.vue | 201 +++ .../appendix/api-intro/FunctionApiDemo.vue | 6 +- .../appendix/api-intro/HttpMethodsDemo.vue | 310 ++++ .../api-intro/StatusCodeCategories.vue | 226 +++ .../computer-fundamentals/AdderChainDemo.vue | 719 ++++++++++ .../CompleteAdderDemo.vue | 1219 ++++++++++++++++ .../computer-fundamentals/FullAdderDemo.vue | 515 +++++++ .../computer-fundamentals/HalfAdderDemo.vue | 229 ++- .../computer-fundamentals/LogicGateDemo.vue | 195 ++- .../appendix/data/ABTestingDemo.vue | 1139 +++++++++++++++ .../appendix/data/DataAnalysisDemo.vue | 1249 ++++++++++++++++ .../appendix/data/DataModelsDemo.vue | 1264 +++++++++++++++++ .../components/appendix/data/SqlDemo.vue | 974 +++++++++++++ .../server-backend/HttpProtocolDemo.vue | 971 +++++++++++++ .../server-backend/SerializationDemo.vue | 564 ++++++++ docs/.vitepress/theme/index.js | 42 +- .../transistor-to-cpu.md | 12 +- .../4-server-and-backend/api-intro.md | 391 +++-- .../4-server-and-backend/http-protocol.md | 298 +++- .../4-server-and-backend/serialization.md | 456 +++++- docs/zh-cn/appendix/5-data/ab-testing.md | 566 +++++++- docs/zh-cn/appendix/5-data/data-analysis.md | 577 +++++++- docs/zh-cn/appendix/5-data/data-models.md | 819 ++++++++++- docs/zh-cn/appendix/5-data/sql.md | 653 ++++++++- 29 files changed, 13338 insertions(+), 389 deletions(-) create mode 100644 docs/.vitepress/theme/components/appendix/api-intro/ApiTypesComparison.vue create mode 100644 docs/.vitepress/theme/components/appendix/api-intro/HttpMethodsDemo.vue create mode 100644 docs/.vitepress/theme/components/appendix/api-intro/StatusCodeCategories.vue create mode 100644 docs/.vitepress/theme/components/appendix/computer-fundamentals/AdderChainDemo.vue create mode 100644 docs/.vitepress/theme/components/appendix/computer-fundamentals/CompleteAdderDemo.vue create mode 100644 docs/.vitepress/theme/components/appendix/computer-fundamentals/FullAdderDemo.vue create mode 100644 docs/.vitepress/theme/components/appendix/data/ABTestingDemo.vue create mode 100644 docs/.vitepress/theme/components/appendix/data/DataAnalysisDemo.vue create mode 100644 docs/.vitepress/theme/components/appendix/data/DataModelsDemo.vue create mode 100644 docs/.vitepress/theme/components/appendix/data/SqlDemo.vue create mode 100644 docs/.vitepress/theme/components/appendix/server-backend/HttpProtocolDemo.vue create mode 100644 docs/.vitepress/theme/components/appendix/server-backend/SerializationDemo.vue diff --git a/docs/.vitepress/theme/components/appendix/api-intro/ApiConceptDemo.vue b/docs/.vitepress/theme/components/appendix/api-intro/ApiConceptDemo.vue index 1bab8f2..40c8c47 100644 --- a/docs/.vitepress/theme/components/appendix/api-intro/ApiConceptDemo.vue +++ b/docs/.vitepress/theme/components/appendix/api-intro/ApiConceptDemo.vue @@ -80,10 +80,8 @@
核心思想： - 无论哪种 API，结构都一样：地址（找谁）+ 参数（要什么）= - 响应（得到什么）。 + 无论哪种 API，结构都一样：地址（找谁）+ 参数（要什么）= + 响应（得到什么）。
diff --git a/docs/.vitepress/theme/components/appendix/api-intro/ApiDocumentDemo.vue b/docs/.vitepress/theme/components/appendix/api-intro/ApiDocumentDemo.vue index 82c9a7a..289a777 100644 --- a/docs/.vitepress/theme/components/appendix/api-intro/ApiDocumentDemo.vue +++ b/docs/.vitepress/theme/components/appendix/api-intro/ApiDocumentDemo.vue @@ -25,8 +25,7 @@
Headers
 Authorization: Bearer sk-xxx
-Content-Type: application/json
+Content-Type: application/json
@@ -69,10 +68,8 @@ response = client.chat.completions.create(
核心思想： - 看文档找三样：地址（Base - URL）、鉴权（Authorization）、参数（Parameters）。 + 看文档找三样：地址（Base + URL）、鉴权（Authorization）、参数（Parameters）。
diff --git a/docs/.vitepress/theme/components/appendix/api-intro/ApiMethodDemo.vue b/docs/.vitepress/theme/components/appendix/api-intro/ApiMethodDemo.vue index 98d148c..cb7a602 100644 --- a/docs/.vitepress/theme/components/appendix/api-intro/ApiMethodDemo.vue +++ b/docs/.vitepress/theme/components/appendix/api-intro/ApiMethodDemo.vue @@ -49,10 +49,8 @@
核心思想： - HTTP 方法就是动词——GET 是"问"，POST 是"做"，PUT/PATCH 是"改"，DELETE - 是"删"。 + HTTP 方法就是动词——GET 是"问"，POST 是"做"，PUT/PATCH 是"改"，DELETE + 是"删"。
diff --git a/docs/.vitepress/theme/components/appendix/api-intro/ApiPlayground.vue b/docs/.vitepress/theme/components/appendix/api-intro/ApiPlayground.vue index d19fe43..ffd8821 100644 --- a/docs/.vitepress/theme/components/appendix/api-intro/ApiPlayground.vue +++ b/docs/.vitepress/theme/components/appendix/api-intro/ApiPlayground.vue @@ -19,7 +19,7 @@ type="text" placeholder="/users" class="input" - > + />
@@ -41,42 +41,24 @@ type="password" placeholder="sk-..." class="input" - > + />
-
-
- 点击发送查看结果 -
-
-
+
点击发送查看结果
+
+
{{ response.status }} {{ response.statusText }} 
{{ JSON.stringify(response.data, null, 2) }}
-
+
💡 {{ response.explanation }}
@@ -85,18 +67,10 @@
快速尝试： - - - - + + + +
@@ -205,9 +179,18 @@ function tryError429() { gap: 8px; } -.icon { font-size: 18px; } -.title { font-weight: 600; font-size: 0.9rem; } -.subtitle { font-size: 0.75rem; color: var(--vp-c-text-3); margin-left: auto; } +.icon { + font-size: 18px; +} +.title { + font-weight: 600; + font-size: 0.9rem; +} +.subtitle { + font-size: 0.75rem; + color: var(--vp-c-text-3); + margin-left: auto; +} .demo-layout { display: flex; @@ -230,8 +213,14 @@ function tryError429() { } @media (max-width: 640px) { - .demo-layout { flex-direction: column; } - .left-panel { width: 100%; border-right: none; border-bottom: 1px solid var(--vp-c-divider); } + .demo-layout { + flex-direction: column; + } + .left-panel { + width: 100%; + border-right: none; + border-bottom: 1px solid var(--vp-c-divider); + } } .input-row { @@ -314,15 +303,31 @@ function tryError429() { font-size: 0.8rem; } -.status-bar.success { background: #dcfce7; } -.status-bar.success .code { color: #166534; } -.status-bar.client-error { background: #fee2e2; } -.status-bar.client-error .code { color: #991b1b; } -.status-bar.server-error { background: #fef3c7; } -.status-bar.server-error .code { color: #92400e; } +.status-bar.success { + background: #dcfce7; +} +.status-bar.success .code { + color: #166534; +} +.status-bar.client-error { + background: #fee2e2; +} +.status-bar.client-error .code { + color: #991b1b; +} +.status-bar.server-error { + background: #fef3c7; +} +.status-bar.server-error .code { + color: #92400e; +} -.code { font-weight: bold; } -.text { color: var(--vp-c-text-2); } +.code { + font-weight: bold; +} +.text { + color: var(--vp-c-text-2); +} .body { flex: 1; diff --git a/docs/.vitepress/theme/components/appendix/api-intro/ApiQuickStartDemo.vue b/docs/.vitepress/theme/components/appendix/api-intro/ApiQuickStartDemo.vue index eb0af8b..c72caf7 100644 --- a/docs/.vitepress/theme/components/appendix/api-intro/ApiQuickStartDemo.vue +++ b/docs/.vitepress/theme/components/appendix/api-intro/ApiQuickStartDemo.vue @@ -89,10 +89,8 @@
核心思想： - 点击按钮 → 发送请求 → 服务器处理 → 返回数据。这就是 API - 调用的完整流程。 + 点击按钮 → 发送请求 → 服务器处理 → 返回数据。这就是 API + 调用的完整流程。
diff --git a/docs/.vitepress/theme/components/appendix/api-intro/ApiTypesComparison.vue b/docs/.vitepress/theme/components/appendix/api-intro/ApiTypesComparison.vue new file mode 100644 index 0000000..74a7717 --- /dev/null +++ b/docs/.vitepress/theme/components/appendix/api-intro/ApiTypesComparison.vue @@ -0,0 +1,201 @@ + + + + + diff --git a/docs/.vitepress/theme/components/appendix/api-intro/FunctionApiDemo.vue b/docs/.vitepress/theme/components/appendix/api-intro/FunctionApiDemo.vue index bf800f9..c8c3b7e 100644 --- a/docs/.vitepress/theme/components/appendix/api-intro/FunctionApiDemo.vue +++ b/docs/.vitepress/theme/components/appendix/api-intro/FunctionApiDemo.vue @@ -53,10 +53,8 @@ result = greet("张三") 核心思想： - 你不需要知道函数内部怎么实现，只需要知道怎么调用它。这就是 API - 的本质。 + 你不需要知道函数内部怎么实现，只需要知道怎么调用它。这就是 API + 的本质。
diff --git a/docs/.vitepress/theme/components/appendix/api-intro/HttpMethodsDemo.vue b/docs/.vitepress/theme/components/appendix/api-intro/HttpMethodsDemo.vue new file mode 100644 index 0000000..22594c9 --- /dev/null +++ b/docs/.vitepress/theme/components/appendix/api-intro/HttpMethodsDemo.vue @@ -0,0 +1,310 @@ + + + + + diff --git a/docs/.vitepress/theme/components/appendix/api-intro/StatusCodeCategories.vue b/docs/.vitepress/theme/components/appendix/api-intro/StatusCodeCategories.vue new file mode 100644 index 0000000..710ab58 --- /dev/null +++ b/docs/.vitepress/theme/components/appendix/api-intro/StatusCodeCategories.vue @@ -0,0 +1,226 @@ + + + + + diff --git a/docs/.vitepress/theme/components/appendix/computer-fundamentals/AdderChainDemo.vue b/docs/.vitepress/theme/components/appendix/computer-fundamentals/AdderChainDemo.vue new file mode 100644 index 0000000..68cee55 --- /dev/null +++ b/docs/.vitepress/theme/components/appendix/computer-fundamentals/AdderChainDemo.vue @@ -0,0 +1,719 @@ + + + + + diff --git a/docs/.vitepress/theme/components/appendix/computer-fundamentals/CompleteAdderDemo.vue b/docs/.vitepress/theme/components/appendix/computer-fundamentals/CompleteAdderDemo.vue new file mode 100644 index 0000000..7a65e78 --- /dev/null +++ b/docs/.vitepress/theme/components/appendix/computer-fundamentals/CompleteAdderDemo.vue @@ -0,0 +1,1219 @@ + + + + + diff --git a/docs/.vitepress/theme/components/appendix/computer-fundamentals/FullAdderDemo.vue b/docs/.vitepress/theme/components/appendix/computer-fundamentals/FullAdderDemo.vue new file mode 100644 index 0000000..4b78540 --- /dev/null +++ b/docs/.vitepress/theme/components/appendix/computer-fundamentals/FullAdderDemo.vue @@ -0,0 +1,515 @@ + + + + + diff --git a/docs/.vitepress/theme/components/appendix/computer-fundamentals/HalfAdderDemo.vue b/docs/.vitepress/theme/components/appendix/computer-fundamentals/HalfAdderDemo.vue index 743fa04..f6c3d57 100644 --- a/docs/.vitepress/theme/components/appendix/computer-fundamentals/HalfAdderDemo.vue +++ b/docs/.vitepress/theme/components/appendix/computer-fundamentals/HalfAdderDemo.vue @@ -1,12 +1,22 @@ @@ -166,12 +184,50 @@ const carryOut = computed(() => inputA.value && inputB.value) margin: 1rem 0; } -.demo-label { - font-size: 0.78rem; +.demo-header { + display: flex; + flex-direction: column; + gap: 0.15rem; + margin-bottom: 0.75rem; +} + +.title { + font-size: 0.9rem; font-weight: bold; - color: var(--vp-c-text-2); - margin-bottom: 1rem; - letter-spacing: 0.2px; + color: var(--vp-c-text-1); +} + +.subtitle { + font-size: 0.75rem; + color: var(--vp-c-text-3); +} + +.terms-box { + display: flex; + gap: 0.5rem; + margin-bottom: 0.75rem; + padding: 0.5rem; + background: var(--vp-c-bg-alt); + border-radius: 6px; +} + +.term-item { + flex: 1; + display: flex; + flex-direction: column; + gap: 0.15rem; +} + +.term-name { + font-size: 0.78rem; + font-weight: 600; + color: var(--vp-c-brand-1); +} + +.term-desc { + font-size: 0.68rem; + color: var(--vp-c-text-3); + line-height: 1.3; } .circuit-container { @@ -240,12 +296,6 @@ const carryOut = computed(() => inputA.value && inputB.value) font-size: 1rem; transition: all 0.2s; } -.s-val { - color: var(--vp-c-text-3); -} -.c-val { - color: var(--vp-c-text-3); -} .output-line.active .s-val { background: #dcfce7; @@ -300,27 +350,97 @@ const carryOut = computed(() => inputA.value && inputB.value) box-shadow: 0 0 8px var(--vp-c-brand-soft); } +.gate-header { + display: flex; + align-items: baseline; + gap: 0.25rem; +} + .gate-name { font-weight: bold; font-size: 0.9rem; color: var(--vp-c-text-1); } +.gate-cn { + font-size: 0.7rem; + color: var(--vp-c-text-3); +} + +.gate-formula { + font-size: 0.75rem; + color: var(--vp-c-brand-1); + font-family: 'JetBrains Mono', monospace; +} + .gate-desc { font-size: 0.65rem; color: var(--vp-c-text-3); - margin-top: 0.2rem; + margin-top: 0.15rem; } -.logic-explain { - margin-top: 1.5rem; - padding: 0.8rem; +.calculation-box { + margin-top: 1rem; + padding: 0.6rem 0.8rem; background: var(--vp-c-bg); border-radius: 6px; - font-size: 0.85rem; - text-align: center; +} + +.calc-title { + font-size: 0.75rem; + font-weight: 600; color: var(--vp-c-text-2); - line-height: 1.5; + margin-bottom: 0.4rem; +} + +.calc-content { + display: flex; + flex-direction: column; + gap: 0.25rem; +} + +.calc-row { + display: flex; + align-items: baseline; + gap: 0.3rem; + font-size: 0.78rem; +} + +.calc-label { + color: var(--vp-c-text-3); + min-width: 3.5rem; +} + +.calc-formula { + font-family: 'JetBrains Mono', monospace; + color: var(--vp-c-text-1); +} + +.calc-formula strong { + color: var(--vp-c-brand-1); +} + +.calc-reason { + color: var(--vp-c-text-3); + font-size: 0.72rem; +} + +.info-box { + display: flex; + gap: 0.25rem; + margin-top: 0.75rem; + padding: 0.6rem 0.8rem; + background: var(--vp-c-bg-alt); + border-radius: 6px; + font-size: 0.8rem; + color: var(--vp-c-text-2); + line-height: 1.4; +} + +.info-box strong { + white-space: nowrap; + flex-shrink: 0; + color: var(--vp-c-text-1); } @media (max-width: 600px) { @@ -329,5 +449,8 @@ const carryOut = computed(() => inputA.value && inputB.value) transform-origin: left top; padding-bottom: 0; } + .terms-box { + flex-direction: column; + } } diff --git a/docs/.vitepress/theme/components/appendix/computer-fundamentals/LogicGateDemo.vue b/docs/.vitepress/theme/components/appendix/computer-fundamentals/LogicGateDemo.vue index b5a2401..d79457c 100644 --- a/docs/.vitepress/theme/components/appendix/computer-fundamentals/LogicGateDemo.vue +++ b/docs/.vitepress/theme/components/appendix/computer-fundamentals/LogicGateDemo.vue @@ -1,36 +1,54 @@ @@ -38,7 +56,10 @@ const gates = [ { name: 'AND', - rule: '都为 1 才得 1', + nameCn: '与门', + formula: 'A ∧ B', + rule: '两个都为 1，才输出 1', + intuition: '串联开关：两道门都开才通', rows: [ [0, 0, 0], [0, 1, 0], @@ -48,7 +69,10 @@ const gates = [ }, { name: 'OR', - rule: '有一个 1 就得 1', + nameCn: '或门', + formula: 'A ∨ B', + rule: '有一个为 1，就输出 1', + intuition: '并联开关：任一道门开就通', rows: [ [0, 0, 0], [0, 1, 1], @@ -58,7 +82,10 @@ const gates = [ }, { name: 'NOT', - rule: '取反', + nameCn: '非门', + formula: '¬A', + rule: '输入取反：0 变 1，1 变 0', + intuition: '反向器：开变关，关变开', rows: [ [0, 1], [1, 0] @@ -66,7 +93,10 @@ const gates = [ }, { name: 'XOR', - rule: '不同才得 1', + nameCn: '异或门', + formula: 'A ⊕ B', + rule: '两个不同，才输出 1', + intuition: '差异检测器：相异为真', rows: [ [0, 0, 0], [0, 1, 1], @@ -86,12 +116,22 @@ const gates = [ margin: 1rem 0; } -.demo-label { - font-size: 0.78rem; - font-weight: bold; - color: var(--vp-c-text-2); +.demo-header { + display: flex; + flex-direction: column; + gap: 0.15rem; margin-bottom: 0.75rem; - letter-spacing: 0.2px; +} + +.title { + font-size: 0.9rem; + font-weight: bold; + color: var(--vp-c-text-1); +} + +.subtitle { + font-size: 0.75rem; + color: var(--vp-c-text-3); } .gates-grid { @@ -108,23 +148,80 @@ const gates = [ text-align: center; } -.gate-name { +.gate-header { + display: flex; + align-items: baseline; + justify-content: center; + gap: 0.3rem; + margin-bottom: 0.3rem; +} + +.gate-name-en { font-weight: bold; - font-size: 0.9rem; + font-size: 1rem; color: var(--vp-c-brand-1); - margin-bottom: 0.15rem; +} + +.gate-name-cn { + font-size: 0.75rem; + color: var(--vp-c-text-2); + font-weight: 500; +} + +.gate-formula { + display: flex; + align-items: center; + justify-content: center; + gap: 0.2rem; + margin-bottom: 0.25rem; +} + +.formula-label { + font-size: 0.65rem; + color: var(--vp-c-text-3); +} + +.formula-code { + font-size: 0.8rem; + padding: 0.1rem 0.3rem; + background: var(--vp-c-bg-alt); + border-radius: 3px; + color: var(--vp-c-brand-1); + font-family: 'JetBrains Mono', monospace; } .gate-rule { font-size: 0.72rem; + color: var(--vp-c-text-2); + margin-bottom: 0.2rem; + font-weight: 500; +} + +.gate-intuition { + font-size: 0.68rem; color: var(--vp-c-text-3); margin-bottom: 0.5rem; + padding: 0.2rem 0.4rem; + background: var(--vp-c-bg-alt); + border-radius: 4px; +} + +.truth-section { + margin-top: 0.3rem; +} + +.truth-title { + font-size: 0.6rem; + color: var(--vp-c-text-3); + margin-bottom: 0.2rem; + text-transform: uppercase; + letter-spacing: 0.5px; } .mini-truth { width: 100%; border-collapse: collapse; - font-size: 0.8rem; + font-size: 0.78rem; font-variant-numeric: tabular-nums; } @@ -137,7 +234,7 @@ const gates = [ .mini-truth th { background: var(--vp-c-bg-alt); - font-size: 0.72rem; + font-size: 0.7rem; font-weight: 600; color: var(--vp-c-text-2); } @@ -145,13 +242,25 @@ const gates = [ .result-cell.one { color: var(--vp-c-brand-1); font-weight: bold; + background: var(--vp-c-brand-soft); } -.demo-caption { - font-size: 0.72rem; - color: var(--vp-c-text-3); - margin-top: 0.6rem; - text-align: center; +.info-box { + display: flex; + gap: 0.25rem; + margin-top: 0.75rem; + padding: 0.6rem 0.8rem; + background: var(--vp-c-bg-alt); + border-radius: 6px; + font-size: 0.8rem; + color: var(--vp-c-text-2); + line-height: 1.4; +} + +.info-box strong { + white-space: nowrap; + flex-shrink: 0; + color: var(--vp-c-text-1); } @media (max-width: 600px) { diff --git a/docs/.vitepress/theme/components/appendix/data/ABTestingDemo.vue b/docs/.vitepress/theme/components/appendix/data/ABTestingDemo.vue new file mode 100644 index 0000000..fb72f84 --- /dev/null +++ b/docs/.vitepress/theme/components/appendix/data/ABTestingDemo.vue @@ -0,0 +1,1139 @@ + + + + + diff --git a/docs/.vitepress/theme/components/appendix/data/DataAnalysisDemo.vue b/docs/.vitepress/theme/components/appendix/data/DataAnalysisDemo.vue new file mode 100644 index 0000000..4843d3f --- /dev/null +++ b/docs/.vitepress/theme/components/appendix/data/DataAnalysisDemo.vue @@ -0,0 +1,1249 @@ + + + + + diff --git a/docs/.vitepress/theme/components/appendix/data/DataModelsDemo.vue b/docs/.vitepress/theme/components/appendix/data/DataModelsDemo.vue new file mode 100644 index 0000000..cf126cc --- /dev/null +++ b/docs/.vitepress/theme/components/appendix/data/DataModelsDemo.vue @@ -0,0 +1,1264 @@ + + + + + diff --git a/docs/.vitepress/theme/components/appendix/data/SqlDemo.vue b/docs/.vitepress/theme/components/appendix/data/SqlDemo.vue new file mode 100644 index 0000000..5d9c760 --- /dev/null +++ b/docs/.vitepress/theme/components/appendix/data/SqlDemo.vue @@ -0,0 +1,974 @@ + + + + + diff --git a/docs/.vitepress/theme/components/appendix/server-backend/HttpProtocolDemo.vue b/docs/.vitepress/theme/components/appendix/server-backend/HttpProtocolDemo.vue new file mode 100644 index 0000000..240df05 --- /dev/null +++ b/docs/.vitepress/theme/components/appendix/server-backend/HttpProtocolDemo.vue @@ -0,0 +1,971 @@ + + + + + diff --git a/docs/.vitepress/theme/components/appendix/server-backend/SerializationDemo.vue b/docs/.vitepress/theme/components/appendix/server-backend/SerializationDemo.vue new file mode 100644 index 0000000..d4ba0c6 --- /dev/null +++ b/docs/.vitepress/theme/components/appendix/server-backend/SerializationDemo.vue @@ -0,0 +1,564 @@ + + + + + diff --git a/docs/.vitepress/theme/index.js b/docs/.vitepress/theme/index.js index 273529f..f9d07fb 100644 --- a/docs/.vitepress/theme/index.js +++ b/docs/.vitepress/theme/index.js @@ -42,6 +42,10 @@ import ApiMethodDemo from './components/appendix/api-intro/ApiMethodDemo.vue' import ApiDocumentDemo from './components/appendix/api-intro/ApiDocumentDemo.vue' import ApiPlayground from './components/appendix/api-intro/ApiPlayground.vue' import RealWorldApiDemo from './components/appendix/api-intro/RealWorldApiDemo.vue' +import FunctionApiDemo from './components/appendix/api-intro/FunctionApiDemo.vue' +import ApiTypesComparison from './components/appendix/api-intro/ApiTypesComparison.vue' +import HttpMethodsDemo from './components/appendix/api-intro/HttpMethodsDemo.vue' +import StatusCodeCategories from './components/appendix/api-intro/StatusCodeCategories.vue' // LLM Intro Components import EmbeddingDemo from './components/appendix/llm-intro/EmbeddingDemo.vue' @@ -106,8 +110,13 @@ import NetworkTroubleshooting from './components/appendix/web-basics/NetworkTrou // Computer Fundamentals Components import TransistorDemo from './components/appendix/computer-fundamentals/TransistorDemo.vue' import LogicGateDemo from './components/appendix/computer-fundamentals/LogicGateDemo.vue' +import HalfAdderDemo from './components/appendix/computer-fundamentals/HalfAdderDemo.vue' +import FullAdderDemo from './components/appendix/computer-fundamentals/FullAdderDemo.vue' import AdderDemo from './components/appendix/computer-fundamentals/AdderDemo.vue' -// import CpuArchitectureDemo from './components/appendix/computer-fundamentals/CpuArchitectureDemo.vue' +import AdderChainDemo from './components/appendix/computer-fundamentals/AdderChainDemo.vue' +import CompleteAdderDemo from './components/appendix/computer-fundamentals/CompleteAdderDemo.vue' +import FunctionalUnitDemo from './components/appendix/computer-fundamentals/FunctionalUnitDemo.vue' +import CpuArchitectureDemo from './components/appendix/computer-fundamentals/CpuArchitectureDemo.vue' import RegisterDemo from './components/appendix/computer-fundamentals/RegisterDemo.vue' // import EvolutionFlowDemo from './components/appendix/computer-fundamentals/EvolutionFlowDemo.vue' import ProcessDemo from './components/appendix/computer-fundamentals/ProcessDemo.vue' @@ -614,6 +623,16 @@ import InterfaceDemo from './components/appendix/typescript-intro/InterfaceDemo. import GenericDemo from './components/appendix/typescript-intro/GenericDemo.vue' import TypeInferenceDemo from './components/appendix/typescript-intro/TypeInferenceDemo.vue' +// Server & Backend Components +import SerializationDemo from './components/appendix/server-backend/SerializationDemo.vue' +import HttpProtocolDemo from './components/appendix/server-backend/HttpProtocolDemo.vue' + +// Data Components +import SqlDemo from './components/appendix/data/SqlDemo.vue' +import DataModelsDemo from './components/appendix/data/DataModelsDemo.vue' +import ABTestingDemo from './components/appendix/data/ABTestingDemo.vue' +import DataAnalysisDemo from './components/appendix/data/DataAnalysisDemo.vue' + export default { extends: DefaultTheme, Layout, @@ -652,6 +671,10 @@ export default { app.component('ApiDocumentDemo', ApiDocumentDemo) app.component('ApiPlayground', ApiPlayground) app.component('RealWorldApiDemo', RealWorldApiDemo) + app.component('FunctionApiDemo', FunctionApiDemo) + app.component('ApiTypesComparison', ApiTypesComparison) + app.component('HttpMethodsDemo', HttpMethodsDemo) + app.component('StatusCodeCategories', StatusCodeCategories) // LLM Intro Components Registration app.component('EmbeddingDemo', EmbeddingDemo) @@ -719,8 +742,13 @@ export default { // Computer Fundamentals Components Registration app.component('TransistorDemo', TransistorDemo) app.component('LogicGateDemo', LogicGateDemo) + app.component('HalfAdderDemo', HalfAdderDemo) + app.component('FullAdderDemo', FullAdderDemo) app.component('AdderDemo', AdderDemo) - // app.component('CpuArchitectureDemo', CpuArchitectureDemo) + app.component('AdderChainDemo', AdderChainDemo) + app.component('CompleteAdderDemo', CompleteAdderDemo) + app.component('FunctionalUnitDemo', FunctionalUnitDemo) + app.component('CpuArchitectureDemo', CpuArchitectureDemo) app.component('RegisterDemo', RegisterDemo) // app.component('EvolutionFlowDemo', EvolutionFlowDemo) app.component('ProcessDemo', ProcessDemo) @@ -1244,6 +1272,16 @@ export default { app.component('InterfaceDemo', InterfaceDemo) app.component('GenericDemo', GenericDemo) app.component('TypeInferenceDemo', TypeInferenceDemo) + + // Server & Backend Components Registration + app.component('SerializationDemo', SerializationDemo) + app.component('HttpProtocolDemo', HttpProtocolDemo) + + // Data Components Registration + app.component('SqlDemo', SqlDemo) + app.component('DataModelsDemo', DataModelsDemo) + app.component('ABTestingDemo', ABTestingDemo) + app.component('DataAnalysisDemo', DataAnalysisDemo) }, setup() { const route = useRoute() diff --git a/docs/zh-cn/appendix/1-computer-fundamentals/transistor-to-cpu.md b/docs/zh-cn/appendix/1-computer-fundamentals/transistor-to-cpu.md index 3faacae..f944d26 100644 --- a/docs/zh-cn/appendix/1-computer-fundamentals/transistor-to-cpu.md +++ b/docs/zh-cn/appendix/1-computer-fundamentals/transistor-to-cpu.md @@ -128,9 +128,13 @@ -再进一步：我们可以把多个半加器和全加器级联组合起来，完成多个位数的加法： +但半加器有个致命缺陷：它无法处理来自低位的进位。在多位加法中，中间的每一位不仅要加 A 和 B，还要加上低位传来的进位。这就需要**全加器（Full Adder）**： - + + +把多个全加器级联起来，就能完成多位数的加法： + + ::: tip 核心解析：分解加法器 为了处理真实世界中更复杂的数字，加法器需要像搭积木一样拼装： @@ -140,6 +144,10 @@ 3. **行波进位加法器（Ripple Carry Adder）**：要想处理 32 位或 64 位的数字，只需要把几十个全加器串联起来。进位信号便像波浪一样从低位一层层涌向高位，从而完成任意大小的加法。 ::: +想要一次性看懂从逻辑门到多位加法的完整过程？试试这个综合演示： + + + --- ## 3. 功能单元：逻辑门的组合 diff --git a/docs/zh-cn/appendix/4-server-and-backend/api-intro.md b/docs/zh-cn/appendix/4-server-and-backend/api-intro.md index 276ee80..2bc7b69 100644 --- a/docs/zh-cn/appendix/4-server-and-backend/api-intro.md +++ b/docs/zh-cn/appendix/4-server-and-backend/api-intro.md @@ -1,179 +1,35 @@ -# API 入门 +# API 入门：从零理解"程序之间的对话" -::: tip 🎯 学习目标 -阅读完本节后，你将能够： -- 理解 API 的本质概念和设计哲学 -- 区分不同类型的 API（函数 API、操作系统 API、Web API） -- 掌握 HTTP 方法的语义和使用场景 -- 学会阅读和使用 API 文档 -- 理解 HTTP 调用与 SDK 调用的区别 +::: tip 🎯 核心问题 +**什么是 API?** 这就像问:餐厅的菜单怎么设计,客人一看就懂?服务员怎么记单,不会出错?API 解决的就是"程序之间如何对话"的问题。你写代码的第一天就在用 API,只是你可能没意识到。 ::: --- -## 1. 从一个按钮开始 +## 0. 新手常见的三个困惑 - +**困惑一:API 是很高深的东西吗?** -👆 看见了吗？点击按钮，几百毫秒后，服务器返回了当前时间。 - -这个过程，就是一次完整的 **API 调用**。虽然简单，但它包含了 API 交互的所有核心要素： - -| 阶段 | 发生了什么 | -|------|-----------| -| **请求** | 客户端向服务器发送 "给我当前时间" 的请求 | -| **处理** | 服务器接收请求，查询系统时间 | -| **响应** | 服务器将时间数据返回给客户端 | - -这就像你去便利店买水——你说"来瓶可乐"，店员给你一瓶可乐。你问一句，他给一笔。 - -**API（Application Programming Interface，应用程序编程接口）**，本质上就是一种"对话约定"：一方提出请求，另一方给出响应。 - ---- - -## 2. API 的三种形态 - -很多人一提到 API，就觉得这是很高深的东西。其实，你写代码的第一天就在用 API 了。 - -### 2.1 函数 API：最基础的形态 - - - -当你调用 `len("hello")` 时，你就在使用 Python 提供的一个 API。你不需要知道 `len()` 内部是怎么数字符串长度的——是用 C 实现的还是用 Python 实现的？是遍历计数还是直接读取长度字段？这些细节都被隐藏了。 - -**API 的核心价值：把复杂的东西藏起来，只给你一个简单的用法。** - -再看一个更贴近实际的例子： +很多人一听到 API,就觉得是高级工程师才能理解的概念。其实你早就用过 API 了: ```python -# 你写这行代码 -response = requests.get("https://api.example.com/users") - -# 背后发生了什么？ -# 1. DNS 解析：把域名转成 IP 地址 -# 2. TCP 连接：建立网络通道 -# 3. TLS 握手：加密通信 -# 4. HTTP 请求：发送数据包 -# 5. 等待响应：接收服务器返回 -# 6. 解析数据：把字节流转成 Python 对象 +len("hello") # 这就是 Python 提供的 API +open("file.txt") # 这也是 API +requests.get(url) # 这还是 API ``` -如果你要自己处理这 6 步，每次请求都要写几百行代码。但 `requests.get()` 把这些都封装好了，你只需要一行代码。 +**困惑二:Web API 和普通 API 有什么区别?** -### 2.2 操作系统 API：让程序能"碰"硬件 +| 类型 | 调用对象 | 通信方式 | 典型场景 | +| :--- | :--- | :--- | :--- | +| **函数 API** | 本地代码 | 函数调用 | `len()`, `open()` | +| **操作系统 API** | 操作系统 | 系统调用 | 读写文件、创建进程 | +| **Web API** | 远程服务器 | HTTP 请求 | 调用 AI 模型、获取天气 | -当你在电脑上打开一个文件： +**困惑三:我该用 HTTP 还是 SDK?** ```python -with open("file.txt", "r") as f: - content = f.read() -``` - -这行代码背后，Python 调用了**操作系统的 API**。 - -| 操作系统 | API 名称 | 作用 | -|---------|---------|------| -| Windows | Win32 API | 文件操作、窗口管理、进程控制 | -| Linux | POSIX API | 系统调用、进程通信、设备访问 | -| macOS | Cocoa API | 图形界面、文件系统、网络 | - -没有操作系统 API，你的 Python 代码就是一堆文字，根本动不了硬盘里的文件、显示不了窗口、连不上网络。 - -### 2.3 Web API：跨越网络的"超能力" - -最后，才是大多数人熟知的 Web API： - -```python -import requests - -response = requests.post( - "https://api.deepseek.com/v1/chat/completions", - headers={"Authorization": "Bearer sk-xxx"}, - json={ - "model": "deepseek-chat", - "messages": [{"role": "user", "content": "你好"}] - } -) -``` - -这行代码做了什么？它让你的程序穿越互联网，调用了千里之外 DeepSeek 服务器上的 AI 模型。就像你打了个越洋电话，让大洋彼岸的厨师帮你做了一道菜。 - -**Web API 的神奇之处：让"调用别人的超级电脑"变得像调用本地函数一样简单。** - ---- - -## 3. API 的统一结构 - -无论哪种 API，结构都一样。就像插头和插座，怎么变都离不开三样东西： - - - -| 要素 | 函数 API | Web API | -|------|---------|---------| -| **地址/名称** | `len()` | `https://api.example.com/users` | -| **输入/参数** | `"hello"` | `{"name": "张三"}` | -| **输出/返回** | `5` | `{"id": 1, "name": "张三"}` | - -理解了这个统一结构，你就掌握了 API 的本质。无论是调用一个 Python 函数，还是请求一个远程服务器，思路都是一样的： - -1. **找到入口**（函数名或 URL） -2. **传入参数**（按要求的格式） -3. **处理返回**（按约定的结构解析） - ---- - -## 4. HTTP 方法：你是在"问"还是在"做"？ - -调用 Web API 时，你需要告诉服务器你想做什么。这就是 HTTP 方法的由来。 - -想象你去一家餐厅： - -| 场景 | 现实中你会怎么说？ | 对应的 HTTP 方法 | -|------|-------------------|-----------------| -| 你想知道今天有什么菜 | "服务员，菜单给我看看" | **GET** - 纯"问"，不改数据 | -| 你想点一份宫保鸡丁 | "给我来份宫保鸡丁" | **POST** - "做"件事，创建数据 | -| 你想换一道菜 | "把宫保鸡丁改成糖醋里脊" | **PUT** - 替换数据 | -| 你想改口味 | "宫保鸡丁不要放花生" | **PATCH** - 部分修改 | -| 你不想要了 | "算了，那道菜不要了" | **DELETE** - 删除数据 | - - - -::: warning 关于幂等性 -**幂等性**是一个重要概念：多次执行结果是否相同？ - -- **GET**：查询 10 次和查询 1 次，结果一样 → 幂等 -- **DELETE**：删除 10 次和删除 1 次，结果一样 → 幂等 -- **POST**：下单 10 次，可能创建 10 个订单 → 不幂等 - -实际开发中，POST 操作通常需要用唯一 ID 来防止重复处理。 -::: - ---- - -## 5. HTTP vs SDK：自己跑腿还是让管家代办？ - -在 AI 编程教程中，你会经常看到两种调用方式：**HTTP** 和 **SDK**。它们的区别就像"自己跑腿"和"让管家代办"。 - - - -### 5.1 HTTP API：自己跑腿 - -这是最原始的方式。你需要： - -1. **找到网址**（Base URL + Endpoint） -2. **准备请求头**（Authorization、Content-Type） -3. **构造请求体**（JSON 格式的参数） -4. **发送请求**（处理网络错误、超时） -5. **解析响应**（把 JSON 转成可用的数据） - -所有编程语言都能用，但你需要处理很多细节。 - -### 5.2 SDK：让管家代办 - -SDK（Software Development Kit）就像是 API 提供方派给你的专属管家： - -```python -# HTTP 方式：自己处理所有细节 +# HTTP 方式:自己处理所有细节 import requests response = requests.post( "https://api.deepseek.com/v1/chat/completions", @@ -182,7 +38,7 @@ response = requests.post( ) result = response.json()["choices"][0]["message"]["content"] -# SDK 方式：管家帮你处理 +# SDK 方式:管家帮你处理 from openai import OpenAI client = OpenAI(api_key="sk-xxx") response = client.chat.completions.create( @@ -192,94 +48,219 @@ response = client.chat.completions.create( result = response.choices[0].message.content ``` -SDK 自动处理了：鉴权、请求格式、错误处理、重试逻辑、响应解析。 +--- -::: tip 建议 -**能用 SDK 就用 SDK**，把麻烦事留给库，把时间留给自己。 +## 1. API 的本质:插头与插座 + +**API**(Application Programming Interface,应用程序编程接口)就是"程序之间对话的约定"。 + +### 1.1 用电器来类比 + +| 概念 | 电器类比 | API 对应 | +| :--- | :--- | :--- | +| **接口** | 插座形状 | 函数签名 / URL | +| **输入** | 电流输入 | 函数参数 / 请求体 | +| **输出** | 电器工作 | 返回值 / 响应体 | + +### 1.2 三种 API 形态对比 + + + +--- + +## 2. 一次完整的 API 调用 + +👇 **动手试试看**:点击下方按钮,观察一次完整的 API 请求-响应流程: + + + +### 2.1 API 调用的四个阶段 + +| 阶段 | 发生了什么 | 电器类比 | +| :--- | :--- | :--- | +| **请求** | 客户端向服务器发送请求 | 按下开关 | +| **传输** | 请求通过网络传输到服务器 | 电流通过电线 | +| **处理** | 服务器处理请求并返回数据 | 电器开始工作 | +| **响应** | 客户端接收并处理返回结果 | 灯泡发光 | + +### 2.2 餐厅类比 + +| 餐厅角色 | API 对应 | 说明 | +| :--- | :--- | :--- | +| **菜单** | API 文档 | 告诉你有哪些"菜"可以点 | +| **服务员** | HTTP 协议 | 标准化的"对话方式" | +| **后厨** | 服务端 | 按"订单"处理请求 | +| **上菜** | 响应 | 把结果返回给"客人" | + +--- + +## 3. HTTP 方法:你是在"问"还是在"做"? + +调用 Web API 时,你需要告诉服务器你想做什么。这就是 HTTP 方法的由来。 + +### 3.1 用餐厅点餐来理解 + +| 场景 | 现实中你会怎么说? | 对应的 HTTP 方法 | +| :--- | :--- | :--- | +| 你想知道今天有什么菜 | "服务员,菜单给我看看" | **GET** - 纯"问",不改数据 | +| 你想点一份宫保鸡丁 | "给我来份宫保鸡丁" | **POST** - "做"件事,创建数据 | +| 你想换一道菜 | "把宫保鸡丁改成糖醋里脊" | **PUT** - 替换数据 | +| 你想改口味 | "宫保鸡丁不要放花生" | **PATCH** - 部分修改 | +| 你不想要了 | "算了,那道菜不要了" | **DELETE** - 删除数据 | + + + +::: warning 关于幂等性 +**幂等性**:多次执行结果是否相同? + +- **幂等的操作**(GET/PUT/DELETE):点 10 次和点 1 次,结果一样 +- **不幂等的操作**(POST):点 10 次,可能创建 10 个订单 + +**解决方案**:POST 操作用唯一 ID 校验,避免重复处理。 +::: + +### 3.2 HTTP 方法速查表 + +| 方法 | 用途 | 幂等性 | 安全性 | 典型场景 | +| :--- | :--- | :--- | :--- | :--- | +| **GET** | 获取资源 | 是 | 是 | 查询列表、查看详情 | +| **POST** | 创建资源 | 否 | 否 | 新增用户、提交订单 | +| **PUT** | 全量更新 | 是 | 否 | 替换整个用户资料 | +| **PATCH** | 部分更新 | 否 | 否 | 只修改昵称 | +| **DELETE** | 删除资源 | 是 | 否 | 删除用户、取消订单 | + +--- + +## 4. HTTP 状态码:服务器在告诉你什么? + +服务器回复时,会先返回一个状态码,告诉你请求是否成功。 + +### 4.1 状态码分类 + + + +### 4.2 常见状态码详解 + +| 状态码 | 含义 | 典型场景 | 客户端处理 | +| :--- | :--- | :--- | :--- | +| **200 OK** | 成功 | 请求正常处理 | 展示数据 | +| **201 Created** | 创建成功 | POST 请求成功创建资源 | 跳转到新资源 | +| **400 Bad Request** | 请求格式错误 | 参数缺失或格式不对 | 检查参数 | +| **401 Unauthorized** | 未认证 | 没有提供有效的 API Key | 引导用户登录 | +| **403 Forbidden** | 无权限 | API Key 没有访问该资源的权限 | 提示权限不足 | +| **404 Not Found** | 不存在 | 请求的地址或资源不存在 | 检查 URL | +| **429 Too Many Requests** | 请求过多 | 超过了速率限制 | 稍后重试 | +| **500 Internal Server Error** | 服务器错误 | 服务端出了问题 | 提示用户稍后重试 | + +👇 **动手试试看**:点击下方按钮,了解常见状态码的含义: + + + +--- + +## 5. HTTP vs SDK:自己跑腿还是让管家代办? + +### 5.1 两种调用方式对比 + +| | 🏃 **HTTP API** | 🤵 **SDK** | +| :--- | :--- | :--- | +| **比喻** | 自己跑腿 | 管家代办 | +| **优点** | ✓ 所有语言都能用
✓ 完全控制请求细节
✓ 无需额外依赖 | ✓ 代码简洁易读
✓ 自动处理鉴权
✓ 内置错误重试 | +| **缺点** | ✗ 需要处理所有细节
✗ 代码冗长易出错 | ✗ 需要安装依赖
✗ 可能有版本问题 | +| **代码示例** | `requests.post(url, json=..., headers={...})` | `client.chat.completions.create(...)` | + +### 5.2 如何选择? + +| 场景 | 推荐方式 | 原因 | +| :--- | :--- | :--- | +| **快速开发** | SDK | 自动处理鉴权、错误、重试 | +| **学习原理** | HTTP | 理解底层机制 | +| **不支持的语言** | HTTP | 任何语言都能用 | +| **需要定制** | HTTP | 灵活控制每个细节 | + +::: tip 💡 建议 +**能用 SDK 就用 SDK**,把麻烦事留给库,把时间留给自己。 ::: --- -## 6. 如何阅读 API 文档？ +## 6. 如何阅读 API 文档? -API 文档就像说明书和菜单的结合体。你不需要从头读到尾，只需要学会"查字典"。 - -打开任何一个 API 文档（比如 OpenAI 或 DeepSeek），你只需要找这几样东西： - - +API 文档就像说明书和菜单的结合体。你不需要从头读到尾,只需要学会"查字典"。 ### 6.1 文档阅读清单 +打开任何一个 API 文档(比如 OpenAI 或 DeepSeek),你只需要找这几样东西: + + + | 项目 | 说明 | 示例 | -|------|------|------| +| :--- | :--- | :--- | | **Base URL** | API 的根地址 | `https://api.deepseek.com` | | **Authentication** | 如何证明身份 | `Authorization: Bearer sk-xxx` | | **Endpoints** | 具体的接口列表 | `/v1/chat/completions` | -| **Parameters** | 必填/可选参数 | `model`（必填）、`temperature`（可选） | +| **Parameters** | 必填/可选参数 | `model`(必填)、`temperature`(可选) | | **Response** | 返回数据结构 | `{"choices": [...]}` | -### 6.2 常见状态码 +### 6.2 阅读文档的步骤 -服务器回复时，会先返回一个状态码，告诉你请求是否成功： - -| 状态码 | 含义 | 常见原因 | -|--------|------|---------| -| **200 OK** | 成功 | 请求正常处理 | -| **201 Created** | 创建成功 | POST 请求成功创建资源 | -| **400 Bad Request** | 请求格式错误 | 参数缺失或格式不对 | -| **401 Unauthorized** | 未认证 | 没有提供有效的 API Key | -| **403 Forbidden** | 无权限 | API Key 没有访问该资源的权限 | -| **404 Not Found** | 不存在 | 请求的地址或资源不存在 | -| **429 Too Many Requests** | 请求过多 | 超过了速率限制 | -| **500 Internal Server Error** | 服务器错误 | 服务端出了问题 | +1. **找到 Base URL** - 这是所有请求的前缀 +2. **看懂认证方式** - API Key 放在 Header 还是 Query? +3. **找到需要的 Endpoint** - 你要调用的具体接口 +4. **查看请求参数** - 哪些必填?哪些可选? +5. **理解返回格式** - 数据是如何组织的? --- -## 7. 动手练习 +## 7. 动手练习:模拟 API 调用 -光说不练假把式。这里有个模拟 API，你可以随便填参数、随便改地址，看看会发生什么。 +光说不练假把式。这里有个模拟 API,你可以随便填参数、随便改地址,看看会发生什么。 -试着触发以下场景： -- ✅ **成功请求**：填入正确的 Endpoint 和 API Key -- ❌ **401 错误**：不填 API Key，看看服务器怎么拒绝你 -- ❌ **404 错误**：填一个不存在的地址 +试着触发以下场景: +- ✅ **成功请求**:填入正确的 Endpoint 和 API Key +- ❌ **401 错误**:不填 API Key,看看服务器怎么拒绝你 +- ❌ **404 错误**:填一个不存在的地址 --- ## 8. 小结 ::: info 核心要点 -1. **API 就是传声筒**，帮你把话传给另一段代码或远程服务器 -2. **你早就用过 API 了**，从 `len()` 到 `open()` 都是 API -3. **Web API 是超能力**，让你调用千里之外的超级电脑 -4. **SDK 是好管家**，能用 SDK 就别自己跑腿 -5. **看文档找三样**：地址、鉴权、参数 +1. **API 就是传声筒**,帮你把话传给另一段代码或远程服务器 +2. **你早就用过 API 了**,从 `len()` 到 `open()` 都是 API +3. **Web API 是超能力**,让你调用千里之外的超级电脑 +4. **SDK 是好管家**,能用 SDK 就别自己跑腿 +5. **看文档找三样**:地址、鉴权、参数 ::: -在 AI 编程的时代，你只需要记住这几个核心概念。剩下的细节，IDE 和 AI 助手会帮你处理。 +在 AI 编程的时代,你只需要记住这几个核心概念。剩下的细节,IDE 和 AI 助手会帮你处理。 --- ## 名词速查表 | 名词 | 全称 | 解释 | -|------|------|------| -| **API** | Application Programming Interface | 应用程序编程接口，定义了软件之间如何交互 | -| **Web API** | - | 基于 HTTP 协议的 API，用于网络通信 | -| **Endpoint** | - | 端点，API 的具体地址 | +| :--- | :--- | :--- | +| **API** | Application Programming Interface | 应用程序编程接口,定义了软件之间如何交互 | +| **Web API** | - | 基于 HTTP 协议的 API,用于网络通信 | +| **Endpoint** | - | 端点,API 的具体地址 | | **HTTP** | HyperText Transfer Protocol | Web API 使用的通信协议 | | **GET** | - | 获取资源的方法 | | **POST** | - | 提交数据的方法 | -| **SDK** | Software Development Kit | 软件开发工具包，封装了底层 API 调用 | +| **SDK** | Software Development Kit | 软件开发工具包,封装了底层 API 调用 | | **URL** | Uniform Resource Locator | API 的网络地址 | | **JSON** | JavaScript Object Notation | 常用的数据格式 | | **Authentication** | - | 验证身份的过程 | | **Status Code** | - | HTTP 响应中的状态码 | | **Request** | - | 请求 | | **Response** | - | 响应 | -| **Header** | - | HTTP 头，包含元信息 | +| **Header** | - | HTTP 头,包含元信息 | | **Payload** | - | 请求或响应的实际数据 | | **Rate Limit** | - | 速率限制 | -| **Idempotent** | - | 幂等，多次执行结果相同 | +| **Idempotent** | - | 幂等,多次执行结果相同 | +| **REST** | Representational State Transfer | 一种 API 架构风格 | +| **RPC** | Remote Procedure Call | 远程过程调用 | +| **GraphQL** | - | 一种查询语言 API | +| **gRPC** | - | Google 开发的高性能 RPC 框架 | diff --git a/docs/zh-cn/appendix/4-server-and-backend/http-protocol.md b/docs/zh-cn/appendix/4-server-and-backend/http-protocol.md index dbb7120..881bcde 100644 --- a/docs/zh-cn/appendix/4-server-and-backend/http-protocol.md +++ b/docs/zh-cn/appendix/4-server-and-backend/http-protocol.md @@ -1,3 +1,297 @@ -# HTTP 协议 +# HTTP 协议：前后端的"通信语言" -> 待实现 +::: tip 🎯 核心问题 +**HTTP 是如何工作的？** 这就像问：两个人如何对话？需要约定语言、语法、对话规则。HTTP 就是前后端之间的"对话协议"。 +::: + +--- + +## 0. HTTP 的本质 + +**HTTP**（HyperText Transfer Protocol，超文本传输协议）是前后端通信的基础协议。 + +### 0.1 用对话来类比 + +| 对话要素 | HTTP 对应 | 说明 | +| :--- | :--- | :--- | +| 语言 | HTTP 协议 | 双方都能理解的语言 | +| 语法 | 请求/响应格式 | 怎么"说话" | +| 流程 | 请求-响应模式 | 一问一答 | +| 结束 | 挂断 | TCP 连接关闭 | + +--- + +## 1. HTTP 的发展历程 + +HTTP 从 1991 年诞生至今，经历了多次重大升级。 + + + +### 1.1 版本对比 + +| 版本 | 年份 | 核心改进 | 典型特征 | +| :--- | :--- | :--- | :--- | +| **HTTP/0.9** | 1991 | 仅支持 GET | 纯文本，只有请求，无响应头 | +| **HTTP/1.0** | 1996 | 增加 POST/HEAD | 每个请求一个 TCP 连接 | +| **HTTP/1.1** | 1997 | 持久连接 | Keep-Alive，一个连接多个请求 | +| **HTTP/2** | 2015 | 多路复用 | 二进制帧，头部压缩 | +| **HTTP/3** | 2022 | 基于 QUIC | UDP 传输，解决队头阻塞 | + +::: tip 💡 为什么需要 HTTP/2？ +HTTP/1.1 虽然支持持久连接，但请求必须串行发送（前一个请求的响应返回后，才能发送下一个请求）。HTTP/2 通过多路复用解决了这个问题，可以同时发送多个请求。 +::: + +--- + +## 2. HTTP 请求的结构 + +### 2.1 请求行 + +```http +GET /api/users/123 HTTP/1.1 +``` + +包含三个部分： +- **方法**：GET、POST、PUT、DELETE 等 +- **URL**：请求的资源路径 +- **版本**：HTTP/1.1 或 HTTP/2 + +### 2.2 请求头 + +```http +Host: api.example.com +User-Agent: Mozilla/5.0 +Accept: application/json +Authorization: Bearer xxx +Content-Type: application/json +Content-Length: 45 +``` + +常见请求头： +| 头部 | 说明 | 示例 | +| :--- | :--- | :--- | +| **Host** | 服务器域名 | `api.example.com` | +| **User-Agent** | 客户端信息 | `Mozilla/5.0` | +| **Accept** | 接受的响应类型 | `application/json` | +| **Authorization** | 认证信息 | `Bearer token` | +| **Content-Type** | 请求体类型 | `application/json` | + +### 2.3 请求体 + +```json +{ + "name": "张三", + "email": "zhangsan@example.com" +} +``` + +只有 POST、PUT、PATCH 等方法才有请求体。 + +--- + +## 3. HTTP 响应的结构 + +### 3.1 状态行 + +```http +HTTP/1.1 200 OK +``` + +包含三个部分： +- **版本**：HTTP/1.1 +- **状态码**：200、404、500 等 +- **状态文本**：OK、Not Found 等 + +### 3.2 响应头 + +```http +Content-Type: application/json +Content-Length: 156 +Cache-Control: max-age=3600 +Set-Cookie: session=xxx; HttpOnly +``` + +常见响应头： +| 头部 | 说明 | 示例 | +| :--- | :--- | :--- | +| **Content-Type** | 响应体类型 | `application/json` | +| **Content-Length** | 响应体大小 | `156` | +| **Cache-Control** | 缓存策略 | `max-age=3600` | +| **Set-Cookie** | 设置 Cookie | `session=xxx` | + +### 3.3 响应体 + +```json +{ + "code": 0, + "data": { + "id": 123, + "name": "张三" + } +} +``` + +--- + +## 4. HTTP 方法详解 + +| 方法 | 用途 | 请求体 | 幂等性 | 安全性 | +| :--- | :--- | :--- | :--- | :--- | +| **GET** | 获取资源 | 无 | 是 | 是 | +| **POST** | 创建资源 | 有 | 否 | 否 | +| **PUT** | 全量更新 | 有 | 是 | 否 | +| **PATCH** | 部分更新 | 有 | 否 | 否 | +| **DELETE** | 删除资源 | 无 | 是 | 否 | +| **HEAD** | 获取头部 | 无 | 是 | 是 | +| **OPTIONS** | 查询支持的方法 | 无 | 是 | 是 | + +### 4.1 GET vs POST + +| 特性 | GET | POST | +| :--- | :--- | :--- | +| **参数位置** | URL 查询参数 | 请求体 | +| **缓存** | 可缓存 | 默认不缓存 | +| **书签** | 可添加为书签 | 不可 | +| **历史记录** | 保存在浏览器历史 | 不保存 | +| **数据长度** | 有限制（URL 长度） | 无限制 | +| **安全性** | 参数可见在 URL | 参数在请求体中 | + +::: tip 💡 何时使用 GET/POST？ +- **GET**：查询、获取数据 +- **POST**：创建、提交数据 +- **PUT**：全量更新（替换整个资源） +- **PATCH**：部分更新（只修改指定字段） +- **DELETE**：删除资源 +::: + +--- + +## 5. HTTP 状态码 + +### 5.1 状态码分类 + +| 分类 | 说明 | 典型状态码 | +| :--- | :--- | :--- | +| **2xx** | 成功 | 200 OK、201 Created、204 No Content | +| **3xx** | 重定向 | 301 永久、302 临时、304 未修改 | +| **4xx** | 客户端错误 | 400 参数错误、401 未认证、404 不存在 | +| **5xx** | 服务端错误 | 500 内部错误、503 不可用 | + +### 5.2 常用状态码 + +| 状态码 | 说明 | 使用场景 | +| :--- | :--- | :--- | +| **200 OK** | 请求成功 | GET、PUT 请求成功 | +| **201 Created** | 创建成功 | POST 创建资源成功 | +| **204 No Content** | 无内容 | DELETE 删除成功 | +| **301 Moved Permanently** | 永久重定向 | URL 永久变更 | +| **302 Found** | 临时重定向 | URL 临时变更 | +| **304 Not Modified** | 未修改 | 缓存有效 | +| **400 Bad Request** | 参数错误 | 请求参数格式错误 | +| **401 Unauthorized** | 未认证 | 需要登录 | +| **403 Forbidden** | 无权限 | 已登录但权限不足 | +| **404 Not Found** | 不存在 | 资源不存在 | +| **500 Internal Server Error** | 内部错误 | 服务器异常 | +| **503 Service Unavailable** | 不可用 | 服务器维护或过载 | + +--- + +## 6. HTTPS：安全的 HTTP + +### 6.1 HTTP vs HTTPS + +| 特性 | HTTP | HTTPS | +| :--- | :--- | :--- | +| **协议** | TCP | TCP + SSL/TLS | +| **端口** | 80 | 443 | +| **数据** | 明文传输 | 加密传输 | +| **证书** | 不需要 | 需要 SSL 证书 | +| **性能** | 略快 | 略慢（握手开销） | +| **SEO** | 无影响 | 搜索引擎优先收录 | + +### 6.2 HTTPS 的工作流程 + +1. **Client Hello**：客户端发送支持的加密套件 +2. **Server Hello**：服务器返回证书和选定的加密套件 +3. **验证证书**：客户端验证服务器证书的有效性 +4. **密钥交换**：使用非对称加密交换会话密钥 +5. **加密通信**：使用会话密钥进行对称加密通信 + +::: tip 💡 HTTPS 的优势 +- **防窃听**：数据加密，第三方无法读取 +- **防篡改**：数据完整性校验 +- **防冒充**：SSL 证书验证服务器身份 +::: + +--- + +## 7. HTTP 缓存机制 + +### 7.1 缓存头 + +| 头部 | 说明 | 示例 | +| :--- | :--- | :--- | +| **Cache-Control** | 缓存策略 | `max-age=3600` | +| **ETag** | 资源版本号 | `"33a64df551425fcc"` | +| **Last-Modified** | 最后修改时间 | `Wed, 21 Oct 2015 07:28:00 GMT` | + +### 7.2 缓存策略 + +**强缓存**： +```http +Cache-Control: max-age=3600 +``` +在 3600 秒内，浏览器直接使用缓存，不发送请求。 + +**协商缓存**： +```http +ETag: "33a64df551425fcc" +``` +浏览器发送 `If-None-Match`，服务器返回 304（未修改）或 200（已修改）。 + +--- + +## 8. 常见问题 + +### 8.1 GET 和 POST 的本质区别 + +**误区**：GET 和 POST 的区别只是参数位置不同。 + +**真相**： +- GET 是幂等的，多次请求结果相同 +- POST 是非幂等的，多次请求可能创建多个资源 +- GET 可被缓存，POST 默认不缓存 +- GET 可被书签保存，POST 不可 + +### 8.2 HTTP/1.1 的队头阻塞 + +**问题**：HTTP/1.1 虽然支持持久连接，但请求必须串行发送。前一个请求响应慢，后续请求都要等待。 + +**解决方案**： +- HTTP/2 多路复用 +- 域名分片（多个域名建立多个连接） +- 连接池（限制并发数） + +### 8.3 HTTP/2 的优势 + +| 特性 | HTTP/1.1 | HTTP/2 | +| :--- | :--- | :--- | +| **传输格式** | 文本 | 二进制帧 | +| **多路复用** | 不支持 | 支持 | +| **头部压缩** | 无 | HPACK 算法 | +| **服务器推送** | 不支持 | 支持 | + +--- + +## 名词速查表 + +| 名词 | 英文 | 解释 | +| :--- | :--- | :--- | +| **HTTP** | HyperText Transfer Protocol | 超文本传输协议 | +| **HTTPS** | HTTP Secure | HTTP + SSL/TLS | +| **TCP** | Transmission Control Protocol | 传输控制协议 | +| **SSL/TLS** | Secure Sockets Layer | 安全套接层 | +| **幂等性** | Idempotent | 多次请求结果相同 | +| **持久连接** | Keep-Alive | 一个 TCP 连接发送多个请求 | +| **多路复用** | Multiplexing | 同时发送多个请求 | +| **队头阻塞** | Head-of-Line Blocking | 前面的请求阻塞后面的请求 | diff --git a/docs/zh-cn/appendix/4-server-and-backend/serialization.md b/docs/zh-cn/appendix/4-server-and-backend/serialization.md index 36c3ac6..e44b4eb 100644 --- a/docs/zh-cn/appendix/4-server-and-backend/serialization.md +++ b/docs/zh-cn/appendix/4-server-and-backend/serialization.md @@ -1,3 +1,455 @@ -# 序列化与数据格式 +# 序列化：数据的"翻译" -> 待实现 +::: tip 🎯 核心问题 +**数据如何在网络上传输？** 这就像问：一个人说的话，如何让另一个人听懂？序列化解决的就是"数据翻译"的问题——把内存中的对象翻译成可以传输的格式。 +::: + +--- + +## 序列化数据的必要性 + +在前后端交互过程中，数据需要经历多次"变形"才能从服务器传递到客户端。 + +**场景一：前端收到的数据"变了"** + +```javascript +// 后端发送 +Date birth = new Date(1990, 5, 15) + +// 前端收到 +{ "birth": "1990-06-15T00:00:00Z" } // 字符串！ +``` + +前端想用 `.getFullYear()`，结果报错了——因为这不是 Date 对象，是字符串。 + +**场景二：中文乱码** + +```json +// 期望 +{ "name": "张三" } + +// 实际收到 +{ "name": "å¼ ä¸" } +``` + +字符编码问题导致中文变成乱码。 + +**场景三：性能瓶颈** + +```json +// 一个包含 10000 条商品列表的响应 +{ + "products": [ + { "id": 1, "name": "...", "description": "...", ... }, + // ... 9999 more + ] +} +// 大小：5.2 MB，传输时间：3.5 秒 +``` + +JSON 格式的冗余导致数据包太大，严重影响性能。 + +--- + +**序列化就像"翻译"**——把内存对象"翻译"成可以传输的格式，接收方再"翻译"回去。 + +--- + +## 1. 什么是序列化/反序列化？ + +**序列化**（Serialization）就是把对象转换成可传输格式的过程。 + +**反序列化**（Deserialization）就是把传输格式还原成对象的过程。 + +### 1.1 用寄快递来类比 + +| 寄快递 | 序列化 | 说明 | +| :--- | :--- | :--- | +| 打包物品 | 序列化 | 把物品装箱，贴上标签 | +| 运输 | 网络传输 | 快递车运送到目的地 | +| 拆包取物 | 反序列化 | 收件人打开箱子，取出物品 | + +### 1.2 为什么需要序列化？ + +| 原因 | 说明 | 示例 | +| :--- | :--- | :--- | +| **网络传输** | 网络只能传输字节流 | API 调用、RPC 通信 | +| **持久化存储** | 磁盘只能存储字节 | 保存对象到文件、数据库 | +| **跨语言** | 不同语言的数据结构不同 | Java 对象 → Python 字典 | +| **分布式缓存** | Redis/Memcached 存储字节 | 缓存用户信息 | + +--- + +## 2. 常见的序列化格式 + +👇 **动手试试看**：点击下方按钮，观察不同语言的序列化过程： + + + +### 2.1 JSON：最通用 + +**优点**： +- 可读性好，调试方便 +- 所有语言都支持 +- 浏览器原生支持（`JSON.parse` / `JSON.stringify`） + +**缺点**： +- 体积大（有大量 `{}` `""` 标记） +- 不支持丰富的数据类型（Date、Map、Set 会被转换成字符串） + +**适用场景**： +- 公开 API +- 前后端通信 +- 配置文件 + +### 2.2 XML：曾经的主流 + +```xml + + + 123 + 张三 + zhangsan@example.com + 28 + +``` + +**优点**： +- 结构清晰，支持注释 +- 支持复杂的嵌套结构 +- 有 Schema 验证（XSD） + +**缺点**： +- 体积大，解析慢 +- 标签冗余（``） + +**适用场景**： +- 配置文件（Spring、MyBatis） +- SOAP 协议 +- 复杂数据交换 + +### 2.3 Protobuf：最高效 + +```protobuf +// user.proto +syntax = "proto3"; +message User { + int32 id = 1; + string name = 2; + string email = 3; + int32 age = 4; +} +``` + +**优点**： +- 体积小（比 JSON 小 30-50%） +- 速度快（解析速度快 5-10 倍） +- 向后兼容（新增字段不影响老版本） + +**缺点**： +- 不可读（二进制格式） +- 需要 .proto 文件定义 +- 不支持动态类型 + +**适用场景**： +- 微服务内部通信 +- 高性能场景（游戏、实时通信） +- 移动端 App（节省流量） + +### 2.4 MessagePack：兼顾可读性和性能 + +```json +// MessagePack 是 JSON 的二进制版本 +// 相同数据，MessagePack 比 JSON 小 30% 左右 +``` + +**优点**： +- 比 JSON 小，比 JSON 快 +- 保持 JSON 的数据模型 +- 支持所有 JSON 类型 + +**缺点**： +- 不可读 +- 不如 Protobuf 高效 + +**适用场景**： +- 需要性能但不想用 Protobuf +- Redis 缓存 +- WebSocket 消息 + +--- + +## 3. 各语言序列化方式对比 + +| 语言 | JSON 库 | Protobuf 库 | XML 库 | +| :--- | :--- | :--- | :--- | +| **JavaScript** | `JSON.stringify()` | `protobuf.js` | `fast-xml-parser` | +| **Python** | `json.dumps()` | `protobuf` | `xmltodict` | +| **Java** | `Jackson` / `Gson` | `protobuf-java` | `JAXB` | +| **Go** | `encoding/json` | `proto` | `encoding/xml` | +| **C++** | `nlohmann/json` | `protobuf` | `tinyxml2` | +| **C#** | `System.Text.Json` | `Google.Protobuf` | `System.Xml` | + +::: tip 💡 选择建议 +- **前后端通信**：JSON（调试方便） +- **微服务内部**：Protobuf（性能最优） +- **配置文件**：JSON 或 YAML +- **旧系统对接**：XML（可能别无选择） +::: + +--- + +## 4. 性能对比 + +### 4.1 大小对比（以用户对象为例） + +| 格式 | 大小 | 相对 JSON | +| :--- | :--- | :--- | +| JSON | 68 bytes | 100% | +| XML | 142 bytes | 209% | +| Protobuf | 38 bytes | 56% | +| MessagePack | 52 bytes | 76% | + +### 4.2 速度对比（序列化 10000 次） + +| 格式 | 耗时 | 相对 JSON | +| :--- | :--- | :--- | +| JSON | 45 ms | 100% | +| XML | 120 ms | 267% | +| Protobuf | 8 ms | 18% | +| MessagePack | 28 ms | 62% | + +::: tip 💡 性能测试结论 +- **Protobuf 最快**：适合高性能场景 +- **MessagePack 次之**：比 JSON 快 40% 左右 +- **JSON 最慢**：但对大多数场景已经足够 +::: + +--- + +## 5. 常见问题 + +### 5.1 日期序列化问题 + +**问题**：Date 对象序列化后变成字符串 + +```javascript +// 序列化前 +const date = new Date('2024-01-01') + +// 序列化后 +JSON.stringify(date) // "2024-01-01T00:00:00.000Z" +``` + +**解决方案**： +```javascript +// 方案1：转成时间戳 +{ createdAt: date.getTime() } // 1704067200000 + +// 方案2：转成 ISO 字符串 +{ createdAt: date.toISOString() } // "2024-01-01T00:00:00.000Z" + +// 方案3：自定义序列化 +JSON.stringify(obj, (key, value) => { + if (value instanceof Date) { + return { __type: 'Date', value: value.toISOString() } + } + return value +}) +``` + +### 5.2 循环引用问题 + +**问题**：对象循环引用会报错 + +```javascript +const obj = { name: 'test' } +obj.self = obj +JSON.stringify(obj) // TypeError: Converting circular structure to JSON +``` + +**解决方案**： +```javascript +// 方案1：过滤掉循环引用 +const seen = new WeakSet() +JSON.stringify(obj, (key, value) => { + if (typeof value === 'object' && value !== null) { + if (seen.has(value)) return + seen.add(value) + } + return value +}) + +// 方案2：使用 flatted 库 +import { parse, stringify } from 'flatted' +stringify(obj) // 自动处理循环引用 +``` + +### 5.3 中文乱码问题 + +**问题**：中文序列化后乱码 + +**原因**： +- 字符编码不一致（UTF-8 vs GBK） +- BOM 标记 + +**解决方案**： +```python +# Python 确保使用 UTF-8 +import json +json.dumps(data, ensure_ascii=False) # 不转义中文 +``` + +```javascript +// Node.js 设置响应头 +res.setHeader('Content-Type', 'application/json; charset=utf-8') +``` + +--- + +## 6. 实战：电商系统序列化方案 + +### 6.1 场景分析 + +| 场景 | 格式选择 | 理由 | +| :--- | :--- | :--- | +| **App → 后端 API** | JSON | 调试方便，前后端统一 | +| **后端 → 后端 RPC** | Protobuf | 性能最优，节省流量 | +| **缓存到 Redis** | MessagePack | 比 JSON 小，可序列化复杂对象 | +| **日志记录** | JSON | 便于日志分析工具解析 | + +### 6.2 代码示例 + +```javascript +// API 响应（JSON） +app.get('/api/products/:id', async (req, res) => { + const product = await db.getProduct(req.params.id) + res.json({ + code: 0, + data: product + }) +}) + +// 微服务通信（Protobuf） +// product.proto +syntax = "proto3"; +message Product { + int32 id = 1; + string name = 2; + int32 price = 3; +} + +// 服务端 +const proto = require('./product.proto') +const message = proto.Product.create(product) +const buffer = proto.Product.encode(message).finish() + +// 客户端 +const decoded = proto.Product.decode(buffer) + +// Redis 缓存（MessagePack） +const msgpack = require('msgpack-lite') +await redis.set( + `product:${id}`, + msgpack.encode(product) +) +const cached = msgpack.decode(await redis.get(`product:${id}`)) +``` + +--- + +## 7. 用 AI 辅助选择序列化方案 + +AI 可以帮助你根据场景选择合适的序列化格式。 + +### 7.1 提示词模板 + +``` +你是一位资深的系统架构师，精通数据序列化技术。请帮我选择合适的序列化方案。 + +## 业务场景 +[描述你的场景，例如：电商 App、游戏后端、微服务等] + +## 技术要求 +[列出约束条件，例如： +- 前后端分离（Vue + Node.js） +- 性能要求高（QPS > 10000） +- 流量敏感（移动端，需节省流量） +- 需要跨语言（Java + Python + Go）] + +## 数据特征 +[描述数据特点，例如： +- 数据量大（单次响应 > 1MB） +- 结构复杂（多层嵌套） +- 包含日期、二进制数据等特殊类型] + +## 输出格式 +请按以下格式输出： +1. 推荐方案（JSON/Protobuf/MessagePack/XML） +2. 理由说明 +3. 性能对比（估算大小和速度） +4. 代码示例 +``` + +### 7.2 实战示例 + +**输入提示词**： + +``` +你是一位资深的系统架构师。我们的电商 App 需要优化商品列表接口性能。 + +## 业务场景 +- 电商 App 的商品列表接口 +- 单次返回 100 个商品 +- 每个 商品包含：id, name, price, image, description 等 20 个字段 +- 当前使用 JSON，响应大小约 200KB，耗时 800ms + +## 技术要求 +- 前端是 Vue.js +- 后端是 Node.js + Go 微服务 +- 需要兼顾性能和开发效率 + +## 优化目标 +- 响应时间降到 300ms 以内 +- 数据包大小减少 30% +``` + +**AI 输出**： + +``` +推荐方案：混合方案 + +1. **API 层**：继续使用 JSON（前端友好） +2. **微服务通信**：切换到 Protobuf（性能提升） +3. **静态数据**：启用 gzip 压缩 + +### 理由说明 +- JSON 对前端最友好，无需额外解析 +- 后端微服务用 Protobuf，可以减少 40% 的数据量 +- gzip 压缩对文本效果明显（JSON 可压缩 70%） + +### 性能对比 +| 方案 | 大小 | 耗时 | +|------|------|------| +| 当前 (JSON) | 200 KB | 800 ms | +| + gzip | 60 KB | 350 ms | +| + Protobuf | 50 KB | 280 ms | + +### 代码示例 +[具体实现代码...] +``` + +--- + +## 名词速查表 + +| 名词 | 英文 | 解释 | +| :--- | :--- | :--- | +| **序列化** | Serialization | 对象 → 字节流 | +| **反序列化** | Deserialization | 字节流 → 对象 | +| **JSON** | JavaScript Object Notation | 最常用的文本格式 | +| **XML** | Extensible Markup Language | 标记语言，曾主流 | +| **Protobuf** | Protocol Buffers | Google 开源的高效格式 | +| **MessagePack** | - | JSON 的二进制版本 | +| **编码** | Encoding | 字符 → 字节 | +| **解码** | Decoding | 字节 → 字符 | diff --git a/docs/zh-cn/appendix/5-data/ab-testing.md b/docs/zh-cn/appendix/5-data/ab-testing.md index e7cbf4a..5208783 100644 --- a/docs/zh-cn/appendix/5-data/ab-testing.md +++ b/docs/zh-cn/appendix/5-data/ab-testing.md @@ -1,3 +1,565 @@ -# A/B 测试与实验驱动 +# A/B 测试：用数据"做决策" -> 待实现 +::: tip 🎯 核心问题 +**如何科学地验证产品改动的效果？** 这就像问：新按钮真的更好用吗？还是用户只是因为新鲜感多点了一下？A/B 测试解决的就是"用数据说话"的问题——不是我觉得好，而是数据证明真的好。 +::: + +--- + +## 0. 先问一个问题：你有没有经历过这些"伪成功"？ + +**场景一：被数据骗了** + +你改了购物车的结算按钮颜色，从蓝变红。一周后一看数据：点击率提升了 30%！ + +你很高兴，宣布大获成功。但三周后，点击率悄悄回到了原水平，甚至还不如之前。 + +**真相**：这是"新奇效应"——用户因为好奇多点了几次，新鲜劲过后就恢复了。 + +**场景二：假阳性陷阱** + +你同时测试了 20 个不同的改进方案。有一个方案显示"统计显著"（p < 0.05），你立即全量上线。 + +一个月后，用户满意度下降了。 + +**真相**：同时测试 20 个方案，即使全部无效，也有 64% 的概率至少有一个"显著"（1 - 0.95^20）。你看到的"显著"只是随机波动。 + +**场景三：辛普森悖论** + +你的数据显示：B 版本的转化率（7.3%）高于 A 版本（5.6%）。但拆分数据后却发现： + +- 移动端：A 8% > B 6% +- 桌面端：A 4% > B 3% + +**每个渠道 A 都更好，但合并后 B 反而赢了**！ + +**真相**：流量分配不均（移动端占 80% 流量，且更多分配给了 B），导致加权平均后 B 看起来更好。 + +--- + +**好的 A/B 测试就像科学的临床试验**——严谨设计、足够样本、长期观察，才能得出可信结论。 + +--- + +## 1. 什么是 A/B 测试？ + +**A/B 测试**是一种对比实验方法：将用户随机分成两组，分别体验不同版本，比较关键指标（如转化率、点击率）的差异，从而判断哪个版本更优。 + +### 1.1 用医学试验来类比 + +| 医学试验 | A/B 测试 | 说明 | +| :--- | :--- | :--- | +| 对照组（安慰剂） | A组（对照组） | 使用当前版本，作为基准 | +| 实验组（新药） | B组（实验组） | 使用新版本，验证效果 | +| 治愈率 | 转化率 | 衡量是否"成功"的指标 | +| 统计显著性 | 统计显著性 | 结果是否可信 | + +**关键原则**：除了版本不同，其他所有条件必须相同（随机分配、同时运行、相同用户群）。 + +### 1.2 A/B 测试的完整流程 + +``` +1. 提出假设 + ↓ +2. 设计实验（确定指标、样本量） + ↓ +3. 开发并部署实验 + ↓ +4. 运行实验（收集数据） + ↓ +5. 分析结果（统计检验） + ↓ +6. 做出决策（全量/放弃/迭代） +``` + +--- + +## 2. A/B 测试的核心价值 + +### 2.1 避免"拍脑袋决策" + +没有 A/B 测试时，决策往往依赖： + +- **HiPPO**（Highest Paid Person's Opinion）：最高领导说了算 +- **设计直觉**：设计师觉得这样更好看 +- **模仿竞品**：竞争对手这么做，我们也这么做 + +**问题**：这些方法都忽略了真实的用户行为。 + +### 2.2 降低风险 + +上线前不知道用户会不会买账？先小范围测试，用 1% 流量验证，避免全量上线后造成损失。 + +### 2.3 持续优化 + +通过不断的小实验，积累小的提升，最终实现显著增长。这就是"增长黑客"的核心方法。 + +--- + +## 3. 实验设计：对照组与实验组 + +### 3.1 随机分配的重要性 + +**正确的做法**：每个用户有 50% 概率进入 A 组，50% 概率进入 B 组 + +**错误的做法**： +- 前半天所有用户进 A 组，后半天进 B 组（时间差异） +- 移动端用户进 A 组，桌面端进 B 组（设备差异） +- 新用户进 A 组，老用户进 B 组（用户类型差异） + +**为什么随机很重要？** + +只有随机分配，才能保证两组用户在其他所有方面都相似（年龄、设备、使用习惯等），这样才能公平比较。 + +### 3.2 流量分配演示 + +👇 **动手试试看**：点击下方按钮，观察流量如何随机分配到两组： + + + +::: tip 💡 50/50 分配是最优的 +虽然有 30/70 或 20/80 的分配策略，但 50/50 能最快检测出差异。除非你对新版本极度不放心，否则不推荐使用非对称分配。 +::: + +--- + +## 4. 样本量计算：需要多少用户才够？ + +### 4.1 为什么不能"看着办"？ + +样本量太小 → 统计功效不足，即使有真实差异也检测不出来（假阴性） +样本量太大 → 浪费资源，运行时间过长 + +**正确做法**：实验前计算所需样本量。 + +### 4.2 影响样本量的四个因素 + +| 因素 | 影响 | 典型值 | +| :--- | :--- | :--- | +| **基准转化率** | 越高，所需样本越少 | 2% - 10% | +| **最小检测提升** | 越小，所需样本越多 | 相对提升 5% - 20% | +| **显著性水平 (α)** | 越小，所需样本越多 | 0.05 (95%置信度) | +| **统计功效 (1-β)** | 越大，所需样本越多 | 0.8 (80%功效) | + +**直觉理解**： +- 你想检测的差异越小（比如只提升 5%），就需要更多样本才能"看清" +- 你想要的结果越确定（比如 99% 置信度 vs 95%），就需要更多证据 + +### 4.3 样本量计算公式 + +对于比例指标（转化率），简化的样本量公式为： + +``` +n = (Zα + Zβ)² × [p1(1-p1) + p2(1-p2)] / (p2 - p1)² +``` + +其中： +- `n` = 每组所需样本量 +- `Zα` = 显著性水平对应的 Z 值（α=0.05 时，Zα=1.96） +- `Zβ` = 统计功效对应的 Z 值（80%功效时，Zβ=0.84） +- `p1` = 基准转化率 +- `p2` = 目标转化率 = p1 × (1 + 相对提升) + +### 4.4 样本量计算示例 + +**场景**：购物车结算按钮，当前转化率 5%，希望检测 20% 的相对提升（即 6%）。 + +- `p1` = 5% = 0.05 +- `p2` = 6% = 0.06 +- `Zα` = 1.96 (α=0.05) +- `Zβ` = 0.84 (80%功效) + +``` +n = (1.96 + 0.84)² × [0.05×0.95 + 0.06×0.94] / (0.06 - 0.05)² +n ≈ 6,932 +``` + +**每组需要 6,932 个样本，两组共需 13,864 个样本**。 + +如果每天有 5,000 个访客，大约需要 **3 天**才能达到足够样本量。 + +::: tip 💡 在线计算工具 +- [Evan Miller 的样本量计算器](https://www.evanmiller.org/ab-testing/sample-size.html) - 业界标准 +- [Optimizely 的样本量计算器](https://www.optimizely.com/sample-size-calculator/) +::: + +--- + +## 5. 统计显著性：如何判断结果"可信"？ + +### 5.1 P 值是什么？ + +**P 值**：如果两个版本真的没有差异（零假设为真），观察到当前数据（或更极端数据）的概率。 + +**通俗理解**：P 值越小，说明"纯属巧合"的可能性越小。 + +**常用阈值**： +- `p < 0.05`：统计显著，有 95% 的信心说差异不是随机的 +- `p < 0.01`：高度显著，有 99% 的信心 +- `p ≥ 0.05`：不显著，差异可能是随机波动 + +### 5.2 置信区间 + +**置信区间**：真实差异可能落入的范围。 + +示例： +- 相对提升：+15% +- 95% 置信区间：[+5%, +25%] + +**解读**：我们有 95% 的信心认为，真实提升在 5% 到 25% 之间。 + +::: warning ⚠️ 常见误解 +置信区间不是"有 95% 的概率在这个区间内"，而是"如果我们重复实验 100 次，95 次的区间会包含真实值"。 + +对于单次实验，真实值要么在区间内，要么不在。但我们不知道是哪种情况。 +::: + +### 5.3 A/B 组结果对比演示 + +👇 **动手试试看**：调整转化率和样本量，观察统计显著性的变化： + + + +**关键观察**： +1. **相对提升越大**，P 值越小（越容易显著） +2. **样本量越大**，P 值越小（越容易显著） +3. **转化率越低**，需要更大样本量才能达到相同显著性 + +--- + +## 6. A/B 测试的常见误区 + +### 6.1 过早停止实验（Peeking 问题） + +**问题**：看到结果"显著"就立即停止实验，不再继续观察。 + +**真相**：P 值会随着数据积累而波动。你看到的"显著"可能只是暂时的随机波动。 + +**Airbnb 的真实案例**： +- 第 7 天：p = 0.05，结果显著，B 版本领先 +- 第 14 天：p = 0.15，不再显著 +- 第 30 天：p = 0.42，完全中性 + +如果第 7 天就停止，就会得出错误的结论。 + +**解决方案**： +- 实验前计算所需样本量，达到后才能分析 +- 使用序贯检验（Sequential Testing），预设"窥探"点和调整后的显著性阈值 + +### 6.2 辛普森悖论 + +**问题**：分组看 B 更差，但合并后 B 反而更好（或相反）。 + +**根本原因**：混淆变量（Confounding Variable）分布不均。 + +**示例**： +``` +移动端（占 80% 流量）： +- A 组：8% 转化率（分配了 40% 流量） +- B 组：6% 转化率（分配了 40% 流量） + +桌面端（占 20% 流量）： +- A 组：4% 转化率（分配了 10% 流量） +- B 组：3% 转化率（分配了 10% 流量） + +合并数据： +- A 组：(8%×0.4 + 4%×0.1) / 0.5 = 7.2% +- B 组：(6%×0.4 + 3%×0.1) / 0.5 = 5.4% + +但如果是这样分配： +移动端：A 组 40% 流量，B 组 40% 流量 +桌面端：A 组 0% 流量，B 组 20% 流量（不平衡！） + +合并数据： +- A 组：(8%×0.4) / 0.4 = 8% +- B 组：(6%×0.4 + 3%×0.2) / 0.6 = 5% +但如果不加权，直接平均：A=5.6%, B=7.3%（B 反而赢了！） +``` + +**解决方案**： +- 确保随机化正确，每个子群体流量分配一致 +- 按关键维度（设备、流量来源、用户类型）分别分析 +- 使用 A/A 测试验证随机化是否有效 + +### 6.3 P-hacking（P 值操纵） + +**问题**：通过尝试不同方法，直到找到"显著"结果。 + +**常见形式**： +- **子群挖掘**：主指标不显著，就按年龄、地区、设备细分，宣称某个子群显著 +- **选择性报告**：同时测了 10 个指标，只报告显著的 1 个 +- **延长实验**：看到 p = 0.06，就再跑几天，"看看能不能降到 0.05 以下" + +**问题**：这些都会大幅增加假阳性率。 + +**解决方案**： +- 预先注册假设和指标，实验过程中不改变 +- 同时测试多个指标时，使用 Bonferroni 校正或 FDR（False Discovery Rate）控制 +- 严格控制"窥探"次数 + +### 6.4 新奇效应 + +**问题**：用户因好奇点击新功能，导致短期数据虚高。 + +**示例**： +- 新按钮上线首周：点击率 +30% +- 第二周：+15% +- 第三周：+5% +- 第四周：0%（甚至 -2%，新鲜感过后，用户发现并不好用） + +**解决方案**： +- 至少运行 2 个完整业务周期（通常 2-4 周） +- 观察趋势是否稳定，而不是只看绝对值 +- 对长期指标（如用户留存）的重视度高于短期指标（如点击率） + +### 6.5 统计功效不足 + +**问题**：样本量太小，即使有真实差异也检测不出来（假阴性）。 + +**示例**：预期提升 5%，但只跑了 1,000 个样本，结果显示"不显著"，你就放弃了。 + +实际上，如果检测 5% 的提升，需要约 30,000 样本才能达到 80% 功效。 + +**解决方案**： +- 实验前必须计算样本量 +- 如果资源有限，可以考虑： + - 提高最小检测提升（比如从 5% 改为 10%） + - 降低统计功效（从 80% 降到 70%，但会增加假阴性风险） + - 延长测试时间 + +--- + +## 7. 实战案例 + +### 7.1 案例 1：按钮颜色测试 + +**背景**：电商网站购物车结算按钮，当前为蓝色，想测试红色是否能提升转化率。 + +**实验设计**： +- 假设：红色按钮更醒目，能提升转化率 10% +- 指标：结算按钮点击率（点击次数 / 访问次数） +- 基准转化率：5% +- 目标转化率：5.5%（相对提升 10%） +- 所需样本量：每组约 30,000（使用在线计算器） +- 流量分配：50/50 +- 显著性水平：α = 0.05 +- 统计功效：80% + +**结果**： +- 运行 7 天后达到所需样本量 +- A 组（蓝）：5.02% +- B 组（红）：5.15% +- 相对提升：+2.6% +- P 值：0.23（不显著） +- 95% 置信区间：[-1.7%, +6.9%] + +**决策**：结果不显著，无法确认红色按钮更好。考虑到： +1. 转化率提升很小（即使真实，也只有 2.6%） +2. 置信区间包含 0（甚至包含负值） +3. 红色按钮可能影响品牌一致性 + +**最终决定**：保持蓝色按钮，尝试其他优化方向（如按钮文案、大小、位置）。 + +--- + +### 7.2 案例 2：注册流程简化 + +**背景**：SaaS 产品注册流程需要填写 10 个字段，想测试减少到 5 个字段是否能提升注册率。 + +**实验设计**： +- 假设：字段更少 → 注册率更高 +- 指标：注册完成率（完成注册数 / 开始注册数） +- 基准转化率：25% +- 目标转化率：30%（相对提升 20%） +- 所需样本量：每组约 2,000 +- 流量分配：50/50 + +**结果**： +- A 组（10 字段）：24.8% +- B 组（5 字段）：31.2% +- 相对提升：+25.8% +- P 值：< 0.001（高度显著） +- 95% 置信区间：[+18.2%, +33.4%] + +**决策**：结果高度显著，全量上线 5 字段版本。 + +**后续跟踪**： +- 新用户注册率提升了 25.8% +- 用户质量（后续付费率）没有下降 +- 用户反馈"注册很快很方便" + +--- + +### 7.3 案例 3：推荐算法优化 + +**背景**：视频网站推荐算法，想测试新的协同过滤算法是否能提升用户观看时长。 + +**实验设计**： +- 假设：新算法推荐更精准 → 观看时长更长 +- 指标：人均每日观看时长（分钟） +- 基准：45 分钟/天 +- 目标：提升 5% → 47.25 分钟/天 +- 所需样本量：每组约 10,000 用户 +- 运行时间：至少 4 周（覆盖完整用户行为周期） + +**结果（4 周后）**： +- A 组（旧算法）：45.2 分钟/天 +- B 组（新算法）：46.8 分钟/天 +- 相对提升：+3.5% +- P 值：0.07（接近显著，但未达到 0.05 阈值） +- 95% 置信区间：[-0.2%, +7.2%] + +**决策**： +1. 统计不显著，但趋势积极（P 值接近 0.05） +2. 置信区间下限接近 0（-0.2%），风险很小 +3. 新算法成本增加不大（服务器资源 +5%） + +**最终决定**：谨慎全量上线，但： +- 持续监控关键指标 +- 准备快速回滚方案 +- 一个月后重新评估 + +**一个月后**： +- 观看时长提升稳定在 +4% +- 用户留存率无显著变化 +- 服务器成本增加可接受 + +结论：实验成功。 + +--- + +## 8. 用 AI 辅助 A/B 测试设计 + +AI 可以帮助你快速设计实验、计算样本量、分析结果。关键在于提供清晰的上下文。 + +### 8.1 提示词模板：样本量计算 + +``` +你是一位资深的 A/B 测试专家。请帮我计算实验所需的样本量。 + +## 业务背景 +[描述你的业务场景，例如：电商网站、SaaS 产品、移动 App] + +## 当前指标 +- 关键指标：[转化率/留存率/点击率等] +- 当前数值：[基准值，如 5%] +- 指标类型：[比例指标/均值指标] + +## 实验设计 +- 预期相对提升：[如 10%，即从 5% 提升到 5.5%] +- 显著性水平 (α)：0.05 (95% 置信度) +- 统计功效 (1-β)：0.8 (80%) +- 流量分配：50/50 + +## 请求 +1. 计算每组所需样本量 +2. 假设每天有 [X] 个访问用户，估算需要运行多少天 +3. 给出实验设计建议 +``` + +### 8.2 提示词模板：结果分析 + +``` +你是一位资深的 A/B 测试专家。请帮我分析实验结果。 + +## 实验结果 +- A 组（对照组）： + - 样本量：10,000 + - 转化数：500 + - 转化率：5.0% + +- B 组（实验组）： + - 样本量：10,000 + - 转化数：550 + - 转化率：5.5% + +## 请求 +1. 计算相对提升（百分比） +2. 计算 Z 值和 P 值 +3. 计算 95% 置信区间 +4. 判断是否统计显著（α = 0.05） +5. 给出决策建议（全量/放弃/继续观察） +6. 指出实验可能存在的偏倚或问题 +``` + +### 8.3 提示词模板：常见问题诊断 + +``` +你是一位资深的 A/B 测试专家。我的实验遇到了问题，请帮我诊断。 + +## 问题描述 +[描述你遇到的问题，例如： +- 运行两周后 P 值仍在 0.5 左右，完全不显著 +- A 组和 B 组数据差异很大，完全不像随机分配 +- 第 3 天结果显示显著，但第 7 天又不显著了] + +## 实验信息 +- 指标：[转化率等] +- 基准值：[如 5%] +- 预期提升：[如 10%] +- 流量分配：[50/50] +- 运行天数：[如 7 天] +- 总样本量：[如 5,000] + +## 请求 +1. 分析可能的原因 +2. 提供诊断建议 +3. 给出解决方案 +``` + +::: tip 💡 追问技巧 +- "请用通俗语言解释什么是 P 值" +- "我的置信区间包含 0，这意味着什么？" +- "如何判断是否存在辛普森悖论？" +- "什么情况下可以使用非 50/50 的流量分配？" +::: + +--- + +## 名词速查表 + +| 名词 | 英文 | 解释 | +| :--- | :--- | :--- | +| **A/B 测试** | A/B Testing | 对比实验，随机分配用户到不同版本，比较指标差异 | +| **对照组** | Control Group | 使用当前版本的组（A 组），作为基准 | +| **实验组** | Treatment Group | 使用新版本的组（B 组），验证效果 | +| **转化率** | Conversion Rate | 完成目标行为的用户占比（如购买、注册） | +| **零假设** | Null Hypothesis | 假设两组没有差异的起点，目标是"推翻"它 | +| **P 值** | P-value | 如果零假设为真，观察到当前数据的概率 | +| **统计显著性** | Statistical Significance | P 值 < 0.05，结果不太可能是随机的 | +| **置信区间** | Confidence Interval | 真实差异可能落入的范围（如 95% CI） | +| **统计功效** | Statistical Power | 检测到真实效应的概率（1-β），通常 80% | +| **第一类错误** | Type I Error | 假阳性（说有差异，实际没有），α 控制 | +| **第二类错误** | Type II Error | 假阴性（说没差异，实际有），β 控制 | +| **显著性水平** | Significance Level | 容忍第一类错误的概率，通常 α = 0.05 | +| **效应量** | Effect Size | 差异的大小（相对提升多少），不只是是否显著 | +| **样本量** | Sample Size | 每组需要的用户数，需提前计算 | +| **随机分配** | Random Assignment | 每个用户有相同概率进入任一组 | +| **单尾检验** | One-tailed Test | 只检验"更好"（不关心"更差"） | +| **双尾检验** | Two-tailed Test | 检验"有差异"（更好或更差都算） | +| **辛普森悖论** | Simpson's Paradox | 分组看趋势一致，合并后趋势相反 | +| **P-hacking** | P-hacking | 操纵数据或方法以获得显著结果 | +| **新奇效应** | Novelty Effect | 用户因好奇产生的短期行为变化 | +| **序贯检验** | Sequential Testing | 预设多个检查点，动态调整显著性阈值 | + +--- + +## 参考资源 + +### 在线工具 +- [Evan Miller - A/B 测试样本量计算器](https://www.evanmiller.org/ab-testing/sample-size.html) +- [Optimizely - 样本量计算器](https://www.optimizely.com/sample-size-calculator/) +- [AB TestGuide - 统计显著性计算器](https://abtestguide.com/calc/) + +### 经典文章 +- [ Airbnb 的实验设计实践](https://medium.com/airbnb-engineering/experimentation-at-airbnb-acquiring-trust-confidence-through-exploratory-data-analysis-9304de556269) +- [Netflix 的 A/B 测试指南](https://netflixtechblog.com/its-all-a-bout-testing-the-netflix-experimentation-platform-4e1ca458c55) +- [Google 的 A/B 测试最佳实践](https://experimentation.com/) + +### 书籍推荐 +- 《Trustworthy Online Controlled Experiments》- Ron Kohavi 等 +- 《Designing Experiments》- Geoffrey Keppel + +### 相关文章 +- [A/B Testing Pitfalls - Simpson's Paradox, P-hacking, Early Stopping](https://blog.example.com/ab-testing-pitfalls) +- [Sample Size Calculation for A/B Testing](https://www.evanmiller.org/ab-testing/sample-size.html) diff --git a/docs/zh-cn/appendix/5-data/data-analysis.md b/docs/zh-cn/appendix/5-data/data-analysis.md index 69436f5..33b9a21 100644 --- a/docs/zh-cn/appendix/5-data/data-analysis.md +++ b/docs/zh-cn/appendix/5-data/data-analysis.md @@ -1,3 +1,576 @@ -# 数据分析基础（统计 / 指标 / 漏斗） +# 数据分析：从数据中"挖掘价值" -> 待实现 +::: tip 核心问题 +**如何从数据中发现规律？** 这就像问：怎么从一堆杂乱的数字里找到有价值的信息？怎么判断业务是否健康？怎么预测未来的趋势？数据分析解决的就是"从数据到洞察"的问题。 +::: + +--- + +## 0. 先问一个问题：你有没有经历过这些困惑？ + +**场景一：被数据淹没** + +``` +系统日志：10 GB/天 +用户行为：100 万条/天 +订单数据：10 万条/天 +``` + +数据堆积如山，但不知道从哪里入手分析，更不知道这些数据能告诉你什么。 + +**场景二：只看表面指标** + +``` +DAU（日活用户）：10 万 → 看起来不错！ +次日留存：15% → 危险！ +30 日留存：3% → 非常危险！ +``` + +只看 DAU 以为产品很成功，但留存率暴跌说明用户来一次就走，产品根本没有粘性。 + +**场景三：不会用 SQL 分析数据** + +``` +想统计：每个用户的平均订单额 +只会写：SELECT * FROM orders; +然后用 Excel 手动计算... +``` + +掌握基本的数据分析技能，能让你从"看数据"变成"用数据驱动决策"。 + +--- + +**好的数据分析就像侦探破案**——从蛛丝马迹中发现规律，从混乱中找到真相。 + +--- + +## 1. 数据分析的价值 + +**数据分析**是从数据中提取有价值信息的过程。它不是简单的"看数字"，而是通过统计、聚合、可视化等方法，发现数据背后的规律和趋势。 + +### 1.1 用医学检查来类比 + +| 医学检查 | 数据分析 | 说明 | +| :--- | :--- | :--- | +| 体温计 | 基础指标 | 温度/DAU 等单一数值 | +| 血常规 | 描述性统计 | 均值、中位数、分布情况 | +| CT 扫描 | 多维度分析 | 从不同角度看数据 | +| 趋势图 | 时间序列分析 | 观察变化趋势 | +| 诊断报告 | 数据洞察 | 得出结论和建议 | + +### 1.2 数据分析的核心价值 + +| 价值 | 说明 | 示例 | +| :--- | :--- | :--- | +| **描述现状** | 告诉你"发生了什么" | 今日 DAU 10 万，销售额 50 万 | +| **诊断问题** | 告诉你"为什么发生" | 留存率低是因为注册流程太长 | +| **预测趋势** | 告诉你"可能发生什么" | 根据过去 30 天数据，下月 DAU 增长 10% | +| **指导决策** | 告诉你"应该怎么做" | A/B 测试显示新版按钮转化率提高 20% | + +--- + +## 2. 描述性统计：从数据中"提炼信息" + +描述性统计是数据分析的基础，它用几个关键指标概括大量数据的特征。 + +### 2.1 集中趋势：数据的"中心"在哪里？ + +| 指标 | 定义 | 适用场景 | 示例 | +| :--- | :--- | :--- | :--- | +| **均值** | 所有数值的平均值 | 数据分布均匀时 | 用户平均年龄：28 岁 | +| **中位数** | 排序后位于中间的值 | 有极端值时 | 收入中位数：5000 元（避免被亿万富翁 skew） | +| **众数** | 出现次数最多的值 | 分类数据 | 最常买的商品：iPhone | + +**为什么需要三个指标？** + +```python +# 场景一：正常分布 +数据：[1, 2, 3, 4, 5] +均值 = 3, 中位数 = 3, 众数 = 无 +→ 数据分布均匀，三个指标接近 + +# 场景二：有极端值 +数据：[1, 2, 3, 4, 100] +均值 = 22, 中位数 = 3 +→ 极端值（100）拉高了均值，中位数更准确 + +# 场景三：电商订单 +数据：[9.9, 9.9, 9.9, 999, 9999] +均值 = 2005.72, 众数 = 9.9 +→ 大部分用户买 9.9 元商品，均值被高客单价 skew +``` + +::: tip 💡 实战建议 +- **DAU、GMV 等指标**：看均值即可（数据量大，极端值影响小） +- **用户收入、房价等**：看中位数更准确（避免被极端值 skew） +- **热销商品、常用功能**：看众数（最典型的情况） +::: + +### 2.2 离散程度：数据"分散"还是"集中"？ + +| 指标 | 定义 | 说明 | +| :--- | :--- | :--- | +| **方差** | 各数据与均值差的平方的平均 | 数值越大，数据越分散 | +| **标准差** | 方差的平方根 | 与原始数据同单位，更直观 | +| **极差** = 最大值 - 最小值 | 最简单的离散度量 | 易受极端值影响 | + +**示例：两个班级的数学成绩** + +``` +A 班：[85, 88, 90, 92, 95] +均值 = 90, 标准差 = 3.16 +→ 成绩集中，水平稳定 + +B 班：[60, 75, 90, 100, 100] +均值 = 85, 标准差 = 16.58 +→ 成绩分散，水平差异大 +``` + +::: tip 💡 标准差的应用 +- **标准差小**：用户行为一致，产品体验稳定 +- **标准差大**：用户群体差异大，可能需要分群分析 +::: + +### 2.3 交互式演示 + +👇 **动手试试看**：在下方输入一组数据，实时计算统计指标： + + + +--- + +## 3. 数据聚合：从明细到"洞察" + +数据聚合是将明细数据按维度汇总，从"看个体"到"看整体"的过程。 + +### 3.1 常用聚合操作 + +| 操作 | SQL 函数 | 说明 | 示例 | +| :--- | :--- | :--- | :--- | +| **计数** | COUNT(*) | 统计行数 | 订单总数 | +| **求和** | SUM(amount) | 累加数值 | 总销售额 | +| **均值** | AVG(amount) | 计算平均 | 平均订单额 | +| **最大值** | MAX(amount) | 找最大值 | 最高单笔订单 | +| **最小值** | MIN(amount) | 找最小值 | 最低单笔订单 | + +### 3.2 分组聚合（GROUP BY） + +**问题**：如何统计每个用户的订单数和总消费？ + +```sql +SELECT + user_id, + COUNT(*) as order_count, + SUM(amount) as total_amount +FROM orders +GROUP BY user_id; +``` + +**结果**： + +| user_id | order_count | total_amount | +| :--- | :--- | :--- | +| U001 | 3 | 480 | +| U002 | 2 | 450 | +| U003 | 1 | 250 | + +::: tip 💡 GROUP BY 的核心思想 +把"明细数据"按某个维度分组，然后对每组进行统计。 +- **维度**：你想分析的角度（用户、商品、日期等） +- **指标**：你想统计的数值（订单数、销售额等） +::: + +### 3.3 多维度聚合 + +**问题**：如何统计每个用户每天的消费？ + +```sql +SELECT + user_id, + date, + SUM(amount) as daily_amount +FROM orders +GROUP BY user_id, date; +``` + +**结果**： + +| user_id | date | daily_amount | +| :--- | :--- | :--- | +| U001 | 2024-01-01 | 100 | +| U001 | 2024-01-02 | 200 | +| U002 | 2024-01-01 | 150 | + +::: warning 常见错误 +```sql +-- ❌ 错误：user_id 没有在 GROUP BY 中 +SELECT user_id, SUM(amount) +FROM orders; + +-- ✅ 正确：所有非聚合字段都要在 GROUP BY 中 +SELECT user_id, SUM(amount) +FROM orders +GROUP BY user_id; +``` +::: + +--- + +## 4. 可视化基础：让数据"会说话" + +好的可视化能让人一眼看懂数据的规律。 + +### 4.1 常用图表类型 + +| 图表类型 | 用途 | 示例 | +| :--- | :--- | :--- | +| **折线图** | 展示趋势 | DAU 变化、销售额增长 | +| **柱状图** | 对比数值 | 各渠道用户数、各品类销售额 | +| **饼图** | 展示占比 | 用户来源分布、商品品类占比 | +| **散点图** | 探索关系 | 广告投入 vs 销售额 | + +### 4.2 图表选择指南 + +| 想展示 | 选择图表 | +| :--- | :--- | +| **随时间的变化** | 折线图 | +| **类别之间的对比** | 柱状图 | +| **部分占整体的比例** | 饼图 | +| **两个变量的关系** | 散点图 | +| **多个变量的分布** | 箱线图 | + +::: tip 💡 可视化原则 +1. **简洁至上**：去掉不必要的装饰（3D 效果、渐变色等） +2. **突出重点**：用颜色、大小强调关键数据 +3. **标注清晰**：标题、坐标轴、图例都要清楚 +4. **避免误导**：Y 轴从 0 开始，不要截断坐标轴 +::: + +--- + +## 5. 数据清洗：垃圾进，垃圾出 + +**"Garbage In, Garbage Out"** —— 如果数据质量差，分析结果就不可信。 + +### 5.1 常见数据问题 + +| 问题类型 | 示例 | 影响 | +| :--- | :--- | :--- | +| **缺失值** | 年龄字段为 NULL | 统计结果偏差 | +| **重复值** | 同一订单出现两次 | 重复计算 | +| **异常值** | 年龄 = 200 岁 | 均值被拉偏 | +| **格式不一致** | 日期：2024-01-01 和 01/01/2024 | 无法正确排序 | + +### 5.2 数据清洗步骤 + +| 步骤 | 操作 | SQL 示例 | +| :--- | :--- | :--- | +| **1. 去重** | 删除重复记录 | `SELECT DISTINCT * FROM orders;` | +| **2. 处理缺失值** | 填充或删除 | `WHERE age IS NOT NULL;` | +| **3. 处理异常值** | 过滤或修正 | `WHERE age BETWEEN 0 AND 120;` | +| **4. 标准化格式** | 统一日期格式 | `TO_DATE(date_str, 'YYYY-MM-DD');` | + +--- + +## 6. 漏斗分析：找到转化瓶颈 + +漏斗分析用于追踪用户在一系列步骤中的转化情况，找到"流失最严重"的环节。 + +### 6.1 什么是漏斗分析？ + +**示例：电商购物流程** + +``` +访问商品页 → 加入购物车 → 进入结算页 → 完成支付 + 10000 → 6000 → 4000 → 2500 + 100% → 60% → 40% → 25% +``` + +**关键指标**： + +| 指标 | 定义 | 示例 | +| :--- | :--- | :--- | +| **转化率** | 进入下一步的人数 / 当前步骤人数 | 60% 的用户加入购物车 | +| **整体转化率** | 最终完成人数 / 初始人数 | 25% 的用户完成购买 | +| **流失率** | 1 - 转化率 | 40% 的用户在购物车环节流失 | + +### 6.2 如何优化漏斗？ + +**步骤 1：找到最弱的环节** + +``` +访问 → 加购 → 结算 → 支付 +100% → 60% → 40% → 25% + -40% -20% -15% +``` + +最大的流失在"访问 → 加购"环节（-40%），说明**商品页没有吸引力**。 + +**步骤 2：针对性优化** + +| 问题环节 | 可能原因 | 优化方案 | +| :--- | :--- | :--- | +| 访问 → 加购 | 商品详情不清晰 | 优化图片、描述、评价 | +| 加购 → 结算 | 运费不透明 | 明确显示总价（含运费） | +| 结算 → 支付 | 支付流程复杂 | 减少表单字段，支持一键支付 | + +--- + +## 7. 留存分析：衡量产品粘性 + +**留存率**衡量用户在首次使用后持续使用的情况，是产品健康度的核心指标。 + +### 7.1 留存率类型 + +| 类型 | 定义 | 计算公式 | 健康标准 | +| :--- | :--- | :--- | :--- | +| **次日留存** | 注册第二天还来的用户占比 | Day 1 活跃 / 注册用户 | > 40% | +| **7 日留存** | 注册第 7 天还来的用户占比 | Day 7 活跃 / 注册用户 | > 20% | +| **30 日留存** | 注册第 30 天还来的用户占比 | Day 30 活跃 / 注册用户 | > 10% | + +### 7.2 如何计算留存率？ + +**示例：1 月 1 日注册的 1000 名用户** + +| 日期 | 注册用户 | 次日留存 | 7 日留存 | 30 日留存 | +| :--- | :--- | :--- | :--- | :--- | +| 2024-01-01 | 1000 | 45% (450 人) | 32% (320 人) | 18% (180 人) | +| 2024-01-02 | 1200 | 42% (504 人) | 28% (336 人) | 15% (180 人) | + +**次日留存率** = 1 月 2 日还活跃的用户 / 1 月 1 日注册用户 += 450 / 1000 = 45% + +### 7.3 留存率的意义 + +| 留存率 | 产品状态 | 说明 | +| :--- | :--- | :--- | +| **高留存** (>40%) | 健康增长 | 用户喜欢，持续使用 | +| **中等留存** (20-40%) | 需要优化 | 产品还行，但不够吸引人 | +| **低留存** (<20%) | 危险 | 用户来一次就走，产品有问题 | + +::: tip 💡 留存 vs DAU +- **高 DAU + 低留存** = "烧钱买量"，不可持续 +- **低 DAU + 高留存** = "慢热型产品"，需要时间积累 +- **高 DAU + 高留存** = 健康增长 🎯 +::: + +--- + +## 8. 实战：用户行为分析 + +假设你负责一个电商 App 的数据分析，以下是完整的分析流程。 + +### 8.1 问题定义 + +**目标**：提高订单转化率 + +**现状**：访问商品页 10 万人，最终下单 2000 人，转化率 2% + +### 8.2 数据收集 + +| 维度 | 数据 | +| :--- | :--- | +| **用户属性** | 年龄、性别、地域、注册时间 | +| **行为数据** | 浏览记录、加购、下单、支付 | +| **交易数据** | 订单金额、商品品类、优惠券使用 | + +### 8.3 数据分析 + +**步骤 1：漏斗分析** + +``` +浏览商品 → 加购 → 结算 → 支付 + 10万 → 5万 → 3万 → 2万 + 100% → 50% → 30% → 2% +``` + +发现："结算 → 支付"环节流失最严重（30% → 2%）。 + +**步骤 2：分群分析** + +```sql +-- 按用户来源分析转化率 +SELECT + traffic_source, + COUNT(*) as total_users, + SUM(CASE WHEN order_id IS NOT NULL THEN 1 ELSE 0 END) as converted_users, + SUM(CASE WHEN order_id IS NOT NULL THEN 1 ELSE 0 END) * 1.0 / COUNT(*) as conversion_rate +FROM user_events +GROUP BY traffic_source; +``` + +**结果**： + +| 来源 | 用户数 | 转化用户 | 转化率 | +| :--- | :--- | :--- | :--- | +| 搜索引擎 | 50000 | 500 | 1% | +| 社交媒体 | 30000 | 900 | 3% | +| 直接访问 | 20000 | 600 | 3% | + +**结论**：搜索引擎用户转化率最低（1%），可能是因为搜索来的用户"只是看看"。 + +**步骤 3：留存分析** + +```sql +-- 不同来源用户的次日留存 +SELECT + traffic_source, + AVG(retention_day1) as avg_retention +FROM user_retention +GROUP BY traffic_source; +``` + +**结果**： + +| 来源 | 次日留存 | +| :--- | :--- | +| 搜索引擎 | 25% | +| 社交媒体 | 45% | +| 直接访问 | 55% | + +**结论**：搜索引擎用户留存低，说明"质量不高"。 + +### 8.4 行动建议 + +| 问题 | 原因 | 建议 | +| :--- | :--- | :--- | +| 转化率低 (2%) | 结算流程复杂 | 简化表单，支持一键支付 | +| 搜索引擎转化低 | 用户意向不明确 | 优化落地页，突出商品价值 | +| 搜索引擎留存低 | 用户找到就离开 | 增加"相关推荐"，引导浏览更多商品 | + +--- + +## 9. 用 AI 辅助数据分析 + +AI 可以帮你快速生成 SQL、分析数据、生成报告。 + +### 9.1 提示词模板 + +``` +你是一位资深的数据分析师，精通 SQL 和数据可视化。请帮我分析以下数据。 + +## 业务背景 +[描述你的业务场景，例如：电商 App、社交媒体等] + +## 数据表结构 +[描述数据表的字段，例如： +- users: user_id, age, gender, register_date +- orders: order_id, user_id, amount, created_at] + +## 分析需求 +[列出你想回答的问题，例如： +1. 统计每个用户的订单数和总消费 +2. 找出消费 Top 10 的用户 +3. 分析用户消费的分布情况] + +## 输出要求 +1. SQL 查询语句 +2. 结果解读 +3. 数据可视化建议 +4. 业务洞察 +``` + +### 9.2 实战示例：用户分群 + +**输入提示词**： + +``` +你是一位资深的数据分析师。请帮我设计一个用户分群方案。 + +## 业务背景 +我是一个电商 App 的数据分析师，我们有 100 万用户，想根据用户的消费行为进行分群，以便精准营销。 + +## 数据表结构 +- orders: order_id, user_id, amount, created_at +- users: user_id, age, gender, register_date + +## 分析需求 +1. 根据 RFM 模型（最近消费、消费频率、消费金额）对用户分群 +2. 计算每个分群的用户数和贡献的销售额 +3. 为每个分群设计营销策略 + +## 输出要求 +请提供： +1. SQL 查询语句 +2. 分群逻辑说明 +3. 每个分群的特征和营销策略 +``` + +**AI 输出示例**： + +```sql +-- RFM 分群 SQL +WITH rfm AS ( + SELECT + user_id, + DATEDIFF('2024-01-31', MAX(created_at)) as recency, + COUNT(*) as frequency, + SUM(amount) as monetary + FROM orders + WHERE created_at >= '2024-01-01' + GROUP BY user_id +), +rfm_scores AS ( + SELECT + user_id, + recency, + frequency, + monetary, + NTILE(4) OVER (ORDER BY recency DESC) as r_score, + NTILE(4) OVER (ORDER BY frequency) as f_score, + NTILE(4) OVER (ORDER BY monetary) as m_score + FROM rfm +) +SELECT + user_id, + CASE + WHEN r_score IN (3, 4) AND f_score IN (3, 4) AND m_score IN (3, 4) THEN '重要价值用户' + WHEN r_score IN (1, 2) AND f_score IN (3, 4) AND m_score IN (3, 4) THEN '重要保持用户' + WHEN r_score IN (3, 4) AND f_score IN (1, 2) AND m_score IN (3, 4) THEN '重要发展用户' + WHEN r_score IN (1, 2) AND f_score IN (1, 2) AND m_score IN (3, 4) THEN '重要挽留用户' + WHEN r_score IN (3, 4) AND f_score IN (3, 4) AND m_score IN (1, 2) THEN '一般价值用户' + WHEN r_score IN (1, 2) AND f_score IN (3, 4) AND m_score IN (1, 2) THEN '一般保持用户' + WHEN r_score IN (3, 4) AND f_score IN (1, 2) AND m_score IN (1, 2) THEN '一般发展用户' + ELSE '流失用户' + END as user_segment +FROM rfm_scores; +``` + +**分群策略**： + +| 分群 | 特征 | 营销策略 | +| :--- | :--- | :--- | +| **重要价值用户** | 最近消费、高频、高金额 | VIP 待遇，专属客服 | +| **重要保持用户** | 很久没来、但曾经高频 | 唤醒活动，优惠券召回 | +| **重要发展用户** | 最近消费、低频、高金额 | 引导复购，推荐关联商品 | +| **重要挽留用户** | 很久没来、低频、高金额 | 主动联系，了解原因 | + +--- + +## 名词速查表 + +| 名词 | 英文 | 解释 | +| :--- | :--- | :--- | +| **描述性统计** | Descriptive Statistics | 用均值、中位数、标准差等指标概括数据 | +| **均值** | Mean | 所有数值的平均值 | +| **中位数** | Median | 排序后位于中间的值 | +| **众数** | Mode | 出现次数最多的值 | +| **标准差** | Standard Deviation | 衡量数据分散程度 | +| **方差** | Variance | 标准差的平方 | +| **聚合** | Aggregation | 将明细数据汇总（求和、计数等） | +| **分组** | Group By | 按某个维度将数据分组 | +| **漏斗分析** | Funnel Analysis | 分析用户在一系列步骤中的转化情况 | +| **转化率** | Conversion Rate | 完成目标行为的用户占比 | +| **留存率** | Retention Rate | 用户持续使用产品的比例 | +| **次日留存** | Day 1 Retention | 注册第二天还活跃的用户占比 | +| **数据清洗** | Data Cleaning | 处理缺失值、重复值、异常值 | +| **可视化** | Visualization | 用图表展示数据 | +| **折线图** | Line Chart | 展示随时间的变化趋势 | +| **柱状图** | Bar Chart | 对比不同类别的数值 | +| **饼图** | Pie Chart | 展示各部分占整体的比例 | +| **散点图** | Scatter Plot | 展示两个变量的关系 | +| **RFM 模型** | RFM Model | 根据最近消费、频率、金额对用户分群 | +| **DAU** | Daily Active Users | 日活跃用户数 | +| **GMV** | Gross Merchandise Value | 商品交易总额 | +| **ARPU** | Average Revenue Per User | 每用户平均收入 | +| **LTV** | Lifetime Value | 用户生命周期价值 | diff --git a/docs/zh-cn/appendix/5-data/data-models.md b/docs/zh-cn/appendix/5-data/data-models.md index 488ff92..9650c97 100644 --- a/docs/zh-cn/appendix/5-data/data-models.md +++ b/docs/zh-cn/appendix/5-data/data-models.md @@ -1,3 +1,818 @@ -# 数据模型全景（文档 / 图 / 时序 / 向量） +# 数据模型：设计的"骨架" -> 待实现 +::: tip 🎯 核心问题 +**如何设计合理的数据结构？** 这就像问：盖房子前怎么画图纸？仓库怎么摆放货物最高效？家族谱系怎么记录最清晰？数据模型解决的就是"数据如何组织"的问题。 +::: + +--- + +## 0. 先问一个问题：你有没有经历过这些噩梦？ + +**场景一：表设计混乱** + +``` +users 表： +| id | name | address | order_1 | order_1_amount | order_2 | order_2_amount | ... | +``` + +订单字段重复 100 次，每次下单都要改表结构。 + +**场景二：数据冗余严重** + +``` +orders 表： +| id | user_name | user_email | user_phone | product_name | product_price | +``` + +用户信息、商品信息全部复制到订单表，修改用户邮箱需要更新所有历史订单。 + +**场景三：关系处理错误** + +``` +posts 表： +| id | title | tags | +| 1 | Vue入门 | vue,frontend,javascript | +``` + +用逗号分隔存储标签，无法查询"有哪些文章包含 vue 标签"。 + +--- + +**好的数据模型就像建筑蓝图**——结构清晰、扩展灵活、关系明确。 + +--- + +## 1. 数据模型的重要性 + +**数据模型**（Data Model）是对现实世界的抽象，描述数据如何存储、组织和关联。 + +### 1.1 用建筑来类比 + +| 建筑概念 | 对应概念 | 说明 | +| :--- | :--- | :--- | +| 蓝图 | 数据模型 | 设计的"骨架"和结构 | +| 承重墙 | 主键/外键 | 保证结构稳固的核心 | +| 房间布局 | 表结构 | 各个功能单元的设计 | +| 水电管线 | 关系 | 连接各个部分的数据流 | + +### 1.2 数据模型的层次 + +| 层次 | 内容 | 示例 | +| :--- | :--- | :--- | +| **概念模型** | 业务对象和关系 | 用户、订单、商品 | +| **逻辑模型** | 表结构、关系类型 | users 表 1:N orders 表 | +| **物理模型** | 具体存储实现 | 字段类型、索引、分区 | + +--- + +## 2. ER 图：实体关系建模 + +**ER 图**（Entity-Relationship Diagram）是用图形化方式描述数据模型的工具。 + +### 2.1 核心概念 + +| 符号 | 含义 | 示例 | +| :--- | :--- | :--- | +| **矩形** | 实体（表） | 用户、订单、商品 | +| **椭圆** | 属性（字段） | 用户名、邮箱、电话 | +| **菱形** | 关系 | 下单、支付、评论 | +| **线条** | 连接 | 表与表的关联 | + +### 2.2 完整的 ER 图示例 + +👇 **动手试试看**：探索用户-订单-商品的实体关系模型： + + + +--- + +## 3. 关系类型：一对一、一对多、多对多 + +关系类型决定了表之间如何关联，是数据模型设计的核心。 + +### 3.1 一对一（One-to-One） + +**定义**：A 表的一条记录对应 B 表的一条记录。 + +**示例**：用户 ↔ 详细资料 + +```sql +users 表： user_profiles 表： +| id | username | | user_id | bio | avatar | +| 1 | 张三 | | 1 | ... | ... | +``` + +**实现方式**： + +```sql +-- 方式 1：外键唯一约束 +CREATE TABLE user_profiles ( + user_id BIGINT PRIMARY KEY, + bio TEXT, + avatar VARCHAR(255), + FOREIGN KEY (user_id) REFERENCES users(id) +); + +-- 方式 2：直接在主表扩展 +CREATE TABLE users ( + id BIGINT PRIMARY KEY, + username VARCHAR(50), + profile_id BIGINT UNIQUE, + FOREIGN KEY (profile_id) REFERENCES user_profiles(id) +); +``` + +**使用场景**： +- 用户表 + 详细资料表（分离敏感信息） +- 订单表 + 支付信息表（分离支付数据） +- 商品表 + 库存表（分离库存管理） + +::: tip 💡 什么时候用一对一？ +当字段数量过多（超过 20 个）或需要分离敏感信息时，考虑拆分为一对一关系。 +::: + +### 3.2 一对多（One-to-Many） + +**定义**：A 表的一条记录对应 B 表的多条记录。 + +**示例**：用户 → 订单 + +```sql +users 表： orders 表： +| id | username | | id | user_id | amount | +| 1 | 张三 | | 1 | 1 | 100 | + | 2 | 1 | 200 | +``` + +**实现方式**： + +```sql +CREATE TABLE orders ( + id BIGINT PRIMARY KEY, + user_id BIGINT NOT NULL, + amount DECIMAL(10,2), + FOREIGN KEY (user_id) REFERENCES users(id) +); + +-- 查询某用户的所有订单 +SELECT * FROM orders WHERE user_id = 1; +``` + +**使用场景**： +- 用户 → 订单 +- 分类 → 商品 +- 部门 → 员工 + +::: tip 💡 最常见的关系 +一对多是关系型数据库中最常见的关系，约占 70% 的场景。 +::: + +### 3.3 多对多（Many-to-Many） + +**定义**：A 表的多条记录对应 B 表的多条记录。 + +**示例**：学生 ↔ 课程 + +```sql +students 表： courses 表： enrollments 表（中间表）： +| id | name | | id | title | | student_id | course_id | +| 1 | 小明 | | 1 | 数学 | | 1 | 1 | +| 2 | 小红 | | 2 | 英语 | | 1 | 2 | + | 2 | 1 | +``` + +**实现方式**： + +```sql +-- 学生表 +CREATE TABLE students ( + id BIGINT PRIMARY KEY, + name VARCHAR(50) +); + +-- 课程表 +CREATE TABLE courses ( + id BIGINT PRIMARY KEY, + title VARCHAR(100) +); + +-- 中间表（选课记录） +CREATE TABLE enrollments ( + student_id BIGINT, + course_id BIGINT, + enrolled_at TIMESTAMP, + PRIMARY KEY (student_id, course_id), + FOREIGN KEY (student_id) REFERENCES students(id), + FOREIGN KEY (course_id) REFERENCES courses(id) +); + +-- 查询小明选的所有课程 +SELECT c.* FROM courses c +JOIN enrollments e ON c.id = e.course_id +WHERE e.student_id = 1; +``` + +**使用场景**： +- 学生 ↔ 课程 +- 用户 ↔ 角色 +- 商品 ↔ 标签 +- 文章 ↔ 分类 + +::: tip 💡 多对多需要中间表 +多对多关系必须通过中间表来实现，中间表包含两个外键，分别指向两张表。 +::: + +--- + +## 4. 范式理论：从混乱到有序 + +**范式**（Normalization）是数据库设计的规范，目的是消除数据冗余，避免数据异常。 + +### 4.1 第一范式（1NF）：字段原子性 + +**要求**：每个字段都是不可再分的最小数据单元。 + +❌ **不符合 1NF**： + +```sql +-- 用户和地址混在一起 +| id | name | contact_info | +| 1 | 张三 | 北京朝阳区,13800138000 | +``` + +✅ **符合 1NF**： + +```sql +| id | name | city | district | phone | +| 1 | 张三 | 北京 | 朝阳区 | 13800138000 | +``` + +::: tip 💡 1NF 是基础 +所有关系型数据库默认都满足 1NF，因为字段本身就不能存储复杂对象（JSON 除外）。 +::: + +### 4.2 第二范式（2NF）：消除部分依赖 + +**要求**：非主键字段必须完全依赖于主键（针对复合主键）。 + +❌ **不符合 2NF**： + +```sql +-- 订单明细表：(order_id, product_id) 是复合主键 +| order_id | product_id | product_name | quantity | unit_price | +| 100 | 1 | iPhone | 2 | 5999 | +``` + +**问题**：`product_name` 和 `unit_price` 只依赖 `product_id`，不依赖 `order_id`。 + +✅ **符合 2NF**： + +```sql +-- 订单明细表 +| order_id | product_id | quantity | +| 100 | 1 | 2 | + +-- 商品表 +| product_id | name | price | +| 1 | iPhone | 5999 | +``` + +::: tip 💡 2NF 针对复合主键 +如果主键是单个字段，则自动满足 2NF。2NF 主要解决复合主键的部分依赖问题。 +::: + +### 4.3 第三范式（3NF）：消除传递依赖 + +**要求**：非主键字段不传递依赖于主键。 + +❌ **不符合 3NF**： + +```sql +-- 订单表 +| id | user_id | total | user_level | discount | +| 1 | 100 | 500 | VIP | 0.9 | +``` + +**问题**：`user_level` 依赖 `user_id`，再依赖 `id`（传递依赖）。 + +✅ **符合 3NF**： + +```sql +-- 订单表 +| id | user_id | total | discount | +| 1 | 100 | 500 | 0.9 | + +-- 用户表 +| id | level | +| 100| VIP | +``` + +::: tip 💡 3NF 是最常见的范式 +实际业务中，大部分表设计都遵循 3NF，它在数据冗余和查询性能之间取得了平衡。 +::: + +### 4.4 范式对比演示 + +👇 **点击下方标签页，查看各范式的对比**： + + + +--- + +## 5. 反范式化：用空间换时间 + +**范式化**虽然能消除冗余，但查询时需要多次 JOIN，影响性能。 + +**反范式化**（Denormalization）是有意增加冗余，换取查询性能提升。 + +### 5.1 何时需要反范式化？ + +| 场景 | 说明 | +| :--- | :--- | +| **高频查询** | 每秒数百次查询，JOIN 成为瓶颈 | +| **大数据量** | 表数据超过千万级，JOIN 性能下降 | +| **报表统计** | 需要聚合计算，预先存储结果 | +| **分布式系统** | 跨库 JOIN 困难，需要冗余数据 | + +### 5.2 反范式化实战 + +**场景**：电商订单查询 + +**范式化设计**： + +```sql +-- 订单表 +orders (id, user_id, total, status) +users (id, name, email) + +-- 查询订单及用户信息 +SELECT o.*, u.name, u.email +FROM orders o +JOIN users u ON o.user_id = u.id +WHERE o.id = 123; +``` + +**性能问题**：每次查询都需要 JOIN，数据量大时慢。 + +**反范式化设计**： + +```sql +-- 订单表（冗余用户信息） +orders (id, user_id, user_name, user_email, total, status) + +-- 查询订单（单表查询） +SELECT * FROM orders WHERE id = 123; +``` + +**性能提升**：无需 JOIN，单表查询速度快 5-10 倍。 + +**代价**： +- 存储空间增加（每个订单多存用户名和邮箱） +- 更新成本增加（修改用户邮箱需更新所有历史订单） + +### 5.3 反范式化的设计原则 + +| 原则 | 说明 | +| :--- | :--- | +| **冗余不经常变化的数据** | 如用户名、商品名称（很少修改） | +| **冗余查询频繁的字段** | 如订单列表展示的用户名、商品图片 | +| **保留原始表** | 范式化表作为"主表"，反范式化表作为"查询表" | +| **数据同步策略** | 通过定时任务、消息队列同步冗余字段 | + +::: warning ⚠️ 反范式化的风险 +- 数据冗余：占用更多存储空间 +- 更新异常：修改数据需同步多处 +- 数据不一致：同步失败导致数据不匹配 + +**建议**：核心交易表保持范式化，查询表、统计表适当反范式化。 +::: + +--- + +## 6. 常见反模式及改进 + +**反模式**（Antipattern）是看似正确但实际有害的设计模式。 + +### 6.1 反模式 1：巨型宽表 + +**错误设计**： + +```sql +-- 将所有数据塞进一张表 +CREATE TABLE big_table ( + id BIGINT, + -- 用户字段 + user_name, user_email, user_phone, + -- 订单字段（重复 100 次） + order_1_id, order_1_amount, order_1_status, + order_2_id, order_2_amount, order_2_status, + -- ... + order_100_id, order_100_amount, order_100_status +); +``` + +**问题**： +- 字段数量爆炸，超过数据库限制 +- 大量空值，浪费存储空间 +- 新增订单需要修改表结构（DDL 操作） +- 无法查询"某个用户的所有订单" + +**正确设计**： + +```sql +-- 用户表 +users (id, name, email, phone) + +-- 订单表 +orders (id, user_id, amount, status, created_at) +``` + +### 6.2 反模式 2：逗号分隔值 + +**错误设计**： + +```sql +-- 文章表，用逗号分隔标签 +posts (id, title, tags) + +| id | title | tags | +| 1 | Vue入门 | vue,frontend,javascript | +``` + +**问题**： +- 无法索引，查询慢 +- 无法关联查询"有哪些文章包含 vue 标签" +- 无法统计"每个标签有多少篇文章" +- 修改标签需要字符串操作 + +**正确设计**： + +```sql +-- 文章表 +posts (id, title) + +-- 标签表 +tags (id, name) + +-- 文章-标签关联表 +post_tags (post_id, tag_id) + +-- 查询包含 vue 标签的文章 +SELECT p.* FROM posts p +JOIN post_tags pt ON p.id = pt.post_id +JOIN tags t ON pt.tag_id = t.id +WHERE t.name = 'vue'; +``` + +### 6.3 反模式 3：滥用 JSON 字段 + +**错误设计**： + +```sql +-- 订单表，订单明细存为 JSON +orders (id, user_id, items, total) + +| id | user_id | items | total | +| 1 | 100 | [{"pid":1,"qty":2},{"pid":2,"qty":1}] | 500 | +``` + +**问题**： +- 无法建立外键约束 +- 无法有效索引（MySQL 5.7+ 部分支持） +- 数据完整性差（插入错误数据无法检测） +- 查询"某个商品的所有订单"需要全文扫描 + +**正确设计**： + +```sql +-- 订单表 +orders (id, user_id, total) + +-- 订单明细表 +order_items (id, order_id, product_id, quantity, price) +``` + +::: tip 💡 什么时候用 JSON？ +JSON 适合存储非结构化、低频查询的数据，如： +- 用户的扩展配置信息 +- 商品的动态属性（不同品类属性不同） +- 日志、埋点数据 +::: + +--- + +## 7. 实战：电商系统数据模型 + +下面是一个完整的电商系统数据模型设计。 + +### 7.1 核心模块 + +**用户模块**： + +```sql +-- 用户表 +users (id, username, email, password_hash, created_at) + +-- 用户地址表 +user_addresses (id, user_id, province, city, district, detail, is_default) + +-- 用户资料表 +user_profiles (id, user_id, nickname, avatar, bio) +``` + +**商品模块**： + +```sql +-- 分类表 +categories (id, name, parent_id, level) + +-- 商品表 +products (id, category_id, name, description, created_at) + +-- 商品 SKU 表 +product_skus (id, product_id, specs, price, stock) + +-- 库存表 +product_inventory (sku_id, warehouse_id, quantity) +``` + +**订单模块**： + +```sql +-- 订单表 +orders ( + id, + user_id, + user_name, -- 冗余，反范式化 + total_amount, + discount_amount, + pay_amount, + status, + created_at +) + +-- 订单明细表 +order_items ( + id, + order_id, + product_id, + product_name, -- 冗余，反范式化 + product_sku_id, + price, + quantity +) + +-- 支付记录表 +payments (id, order_id, amount, method, status, transaction_id) +``` + +**营销模块**： + +```sql +-- 优惠券表 +coupons (id, name, type, discount, min_amount, stock) + +-- 用户优惠券表 +user_coupons (id, user_id, coupon_id, status, used_at) + +-- 促销活动表 +promotions (id, name, type, discount, start_time, end_time) +``` + +### 7.2 关系设计 + +| 关系 | 类型 | 说明 | +| :--- | :--- | :--- | +| users ↔ orders | 1:N | 一个用户有多个订单 | +| orders ↔ order_items | 1:N | 一个订单有多个明细 | +| products ↔ product_skus | 1:N | 一个商品有多个 SKU | +| users & coupons | M:N | 通过 user_coupons 中间表 | +| products & categories | M:N | 一个商品可属于多个分类 | + +### 7.3 反范式化策略 + +| 字段 | 冗余位置 | 原因 | +| :--- | :--- | :--- | +| user_name | orders 表 | 避免查询订单时 JOIN users 表 | +| product_name | order_items 表 | 避免商品改名后历史订单显示问题 | +| product_price | order_items 表 | 保存下单时价格，避免价格变动影响 | + +--- + +## 8. 数据模型设计流程 + +### 8.1 需求分析阶段 + +1. **识别业务实体**：用户、订单、商品、优惠券 +2. **梳理业务关系**：用户下单、商品分类、优惠券使用 +3. **确定数据量级**：预计用户数、订单数、商品数 + +### 8.2 概念模型阶段 + +1. **绘制 ER 图**：用图形化工具（如 draw.io、MySQL Workbench） +2. **标注关系类型**：一对一、一对多、多对多 +3. **确定主外键**：每个表的主键、外键关联 + +### 8.3 逻辑模型阶段 + +1. **设计表结构**：字段名、类型、约束 +2. **应用范式理论**：确保满足 3NF +3. **考虑扩展性**：预留扩展字段（如 ext_json） + +### 8.4 物理模型阶段 + +1. **选择存储引擎**：InnoDB（事务）、MyISAM（只读） +2. **设计索引**：主键索引、外键索引、唯一索引 +3. **分区策略**：按时间、ID 范围分区 + +### 8.5 优化迭代阶段 + +1. **性能测试**：模拟真实查询，分析慢查询 +2. **适当反范式化**：高频查询表冗余字段 +3. **数据归档**：历史数据迁移到归档表 + +--- + +## 9. 用 AI 辅助设计数据模型 + +AI 可以帮你快速生成符合规范的数据模型。关键在于提供清晰的业务描述。 + +### 9.1 提示词模板 + +``` +你是一位资深的数据库架构师，精通关系型数据库设计。请帮我设计数据模型。 + +## 业务背景 +[描述你的业务场景，例如：电商系统、博客平台、任务管理系统] + +## 核心实体 +[列出主要的业务对象，例如： +- 用户：注册、登录、个人信息 +- 订单：下单、支付、发货 +- 商品：分类、库存、价格] + +## 关系说明 +[描述实体之间的关系，例如： +- 一个用户可以有多个订单 +- 一个订单包含多个商品 +- 商品属于分类，多级分类] + +## 设计要求 +1. 遵循 3NF 范式 +2. 明确标注主键（PK）和外键（FK） +3. 说明表之间的一对一、一对多、多对多关系 +4. 考虑反范式化策略（如果需要） +5. 提供完整的建表 SQL（MySQL 语法） + +## 输出格式 +请按以下格式输出： + +### 表结构 +- 表名：说明 + - 字段定义 + +### 关系图 +用文字描述表之间的关系 + +### 索引建议 +列出需要建立的索引 + +### 反范式化建议 +说明哪些字段需要冗余，为什么 +``` + +### 9.2 实战示例：博客系统 + +**输入提示词**： + +``` +你是一位资深的数据库架构师。请帮我设计一个博客系统的数据模型。 + +## 业务背景 +一个多用户博客平台，用户可以发布文章、评论、点赞。 + +## 核心实体 +- 用户：昵称、邮箱、密码 +- 文章：标题、内容、发布时间 +- 评论：评论内容、评论时间 +- 标签：文章可以打多个标签 + +## 关系说明 +- 一个用户可以发表多篇文章 +- 一篇文章可以有多个评论 +- 一篇文章可以有多个标签 +- 一个用户可以点赞多篇文章 + +## 设计要求 +1. 遵循 3NF 范式 +2. 标注 PK 和 FK +3. 说明关系类型 +4. 提供建表 SQL +``` + +**AI 输出示例**： + +```sql +-- 用户表 +CREATE TABLE users ( + id BIGINT PRIMARY KEY AUTO_INCREMENT, + nickname VARCHAR(50) NOT NULL, + email VARCHAR(100) UNIQUE NOT NULL, + password_hash VARCHAR(255) NOT NULL, + created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP +); + +-- 文章表 +CREATE TABLE posts ( + id BIGINT PRIMARY KEY AUTO_INCREMENT, + user_id BIGINT NOT NULL, + title VARCHAR(200) NOT NULL, + content TEXT NOT NULL, + created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP, + FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE +); + +-- 评论表 +CREATE TABLE comments ( + id BIGINT PRIMARY KEY AUTO_INCREMENT, + post_id BIGINT NOT NULL, + user_id BIGINT NOT NULL, + content TEXT NOT NULL, + created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP, + FOREIGN KEY (post_id) REFERENCES posts(id) ON DELETE CASCADE, + FOREIGN KEY (user_id) REFERENCES users(id) +); + +-- 标签表 +CREATE TABLE tags ( + id BIGINT PRIMARY KEY AUTO_INCREMENT, + name VARCHAR(50) UNIQUE NOT NULL +); + +-- 文章-标签关联表 +CREATE TABLE post_tags ( + post_id BIGINT NOT NULL, + tag_id BIGINT NOT NULL, + PRIMARY KEY (post_id, tag_id), + FOREIGN KEY (post_id) REFERENCES posts(id) ON DELETE CASCADE, + FOREIGN KEY (tag_id) REFERENCES tags(id) +); + +-- 点赞表 +CREATE TABLE likes ( + user_id BIGINT NOT NULL, + post_id BIGINT NOT NULL, + created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP, + PRIMARY KEY (user_id, post_id), + FOREIGN KEY (user_id) REFERENCES users(id), + FOREIGN KEY (post_id) REFERENCES posts(id) ON DELETE CASCADE +); + +-- 索引建议 +CREATE INDEX idx_posts_user_id ON posts(user_id); +CREATE INDEX idx_posts_created_at ON posts(created_at DESC); +CREATE INDEX idx_comments_post_id ON comments(post_id); +CREATE INDEX idx_post_tags_tag_id ON post_tags(tag_id); +``` + +### 9.3 AI 辅助设计的注意事项 + +| 注意点 | 说明 | +| :--- | :--- | +| **提供完整上下文** | 业务场景、数据量级、查询模式都要说明 | +| **明确关系类型** | 一对一、一对多、多对多要说清楚 | +| **要求解释原因** | 让 AI 说明为什么这样设计 | +| **检查约束条件** | 主键、外键、唯一索引是否合理 | +| **考虑扩展性** | 询问未来可能的扩展场景 | +| **人工审核** | AI 生成的内容需要人工检查是否符合业务需求 | + +::: tip 💡 追问技巧 +- "请说明这个设计遵循了哪些范式" +- "如果数据量达到千万级，如何优化" +- "哪些字段可以考虑反范式化" +- "请补充索引设计的理由" +::: + +--- + +## 名词速查表 + +| 名词 | 英文 | 解释 | +| :--- | :--- | :--- | +| **数据模型** | Data Model | 对现实世界的抽象，描述数据如何存储、组织和关联 | +| **ER 图** | Entity-Relationship Diagram | 用图形化方式描述实体关系的工具 | +| **主键** | Primary Key | 唯一标识表中每条记录的字段 | +| **外键** | Foreign Key | 关联另一张表主键的字段 | +| **范式** | Normalization | 数据库设计的规范，消除数据冗余 | +| **反范式化** | Denormalization | 有意增加冗余，换取查询性能提升 | +| **一对一** | One-to-One | A 表一条记录对应 B 表一条记录 | +| **一对多** | One-to-Many | A 表一条记录对应 B 表多条记录 | +| **多对多** | Many-to-Many | A 表多条记录对应 B 表多条记录 | +| **中间表** | Junction Table | 实现多对多关系的关联表 | +| **冗余** | Redundancy | 数据重复存储 | +| **传递依赖** | Transitive Dependency | A → B → C，C 传递依赖 A | +| **部分依赖** | Partial Dependency | 非主键字段只依赖复合主键的一部分 | +| **原子性** | Atomicity | 字段不可再分的最小数据单元 | +| **宽表** | Wide Table | 字段数量特别多的表 | +| **索引** | Index | 加速查询的数据结构 | +| **约束** | Constraint | 保证数据完整性的规则（如 NOT NULL、UNIQUE） | diff --git a/docs/zh-cn/appendix/5-data/sql.md b/docs/zh-cn/appendix/5-data/sql.md index e5ff34e..ec5ee0c 100644 --- a/docs/zh-cn/appendix/5-data/sql.md +++ b/docs/zh-cn/appendix/5-data/sql.md @@ -1,3 +1,652 @@ -# SQL +# SQL：与数据库对话的语言 -> 待实现 +::: tip 核心问题 +**如何高效地查询和操作数据？** 这就像问：图书馆的书怎么快速找到？仓库的货物怎么精准定位？银行的账目怎么安全转账？SQL 解决的就是"与数据对话"的问题。 +::: + +--- + +## 0. SQL 的核心价值 + +在现代软件开发中，数据是核心资产。无论是电商平台的商品信息、社交网络的用户关系，还是银行系统的交易记录，都需要一种高效的方式来管理和查询。 + +**SQL**（Structured Query Language，结构化查询语言）就是这样一种"与数据库对话"的语言。它让我们能够： + +- **精准查询**：从百万级数据中快速找到目标 +- **高效操作**：批量增删改，一条语句搞定 +- **安全保障**：事务机制保证数据一致性 +- **标准通用**：学一次，所有数据库都能用 + +--- + +## 1. SQL vs NoSQL：如何选择？ + +在深入了解 SQL 之前，先了解一下它与 NoSQL 的区别。 + +### 1.1 用仓库来类比 + +| 特性 | SQL（关系型数据库） | NoSQL（非关系型数据库） | +| :--- | :--- | :--- | +| **数据结构** | 严格的表结构（像 Excel） | 灵活的文档/键值/图结构 | +| **典型代表** | MySQL、PostgreSQL、Oracle | MongoDB、Redis、Elasticsearch | +| **适用场景** | 金融系统、电商订单、用户管理 | 社交动态、日志分析、实时缓存 | +| **优势** | 数据一致性、事务支持（ACID） | 高并发、灵活扩展、高性能 | +| **劣势** | 扩展性差、schema 固定 | 数据一致性弱、查询功能有限 | + +### 1.2 一个直观的对比 + +**SQL 数据库**就像一个**规范化的仓库**： +- 每个货架有固定的编号、名称、容量 +- 货物必须按照规则摆放 +- 入库、出库有严格的流程和记录 +- 适合需要严格管理的场景 + +**NoSQL 数据库**就像一个**灵活的杂物间**： +- 想放哪里就放哪里 +- 不需要预先规划空间 +- 快速存取，但可能找不到东西 +- 适合需要快速迭代的场景 + +::: tip 💡 实际应用 +大多数企业会**同时使用 SQL 和 NoSQL**： +- MySQL 存储用户信息、订单数据（核心业务） +- Redis 缓存热点数据（提高性能） +- MongoDB 存储日志、用户行为（数据分析） +::: + +--- + +## 2. CRUD 操作：数据的增删改查 + +SQL 的核心操作就是 CRUD（Create, Read, Update, Delete）。 + +### 2.1 用 Excel 来类比 + +| Excel 操作 | SQL 关键字 | 说明 | +| :--- | :--- | :--- | +| 插入新行 | INSERT | 添加数据 | +| 筛选行 | SELECT | 查询数据 | +| 修改单元格 | UPDATE | 更新数据 | +| 删除行 | DELETE | 删除数据 | + +### 2.2 实战演示 + +👇 **动手试试看**：在下方交互式演示中体验 CRUD 操作： + + + +### 2.3 常用查询语法 + +#### **SELECT：查询数据** + +```sql +-- 查询所有列 +SELECT * FROM users; + +-- 查询指定列 +SELECT name, email FROM users; + +-- 带条件查询 +SELECT * FROM users WHERE age > 18; + +-- 排序 +SELECT * FROM users ORDER BY age DESC; + +-- 限制结果数量 +SELECT * FROM users LIMIT 10; +``` + +#### **INSERT：插入数据** + +```sql +-- 插入完整数据 +INSERT INTO users (name, email, age) +VALUES ('张三', 'zhangsan@example.com', 25); + +-- 批量插入 +INSERT INTO users (name, email, age) VALUES + ('李四', 'lisi@example.com', 30), + ('王五', 'wangwu@example.com', 28); +``` + +#### **UPDATE：更新数据** + +```sql +-- 更新单个字段 +UPDATE users SET age = 26 WHERE id = 1; + +-- 更新多个字段 +UPDATE users +SET age = 27, email = 'newemail@example.com' +WHERE id = 1; + +-- ⚠️ 危险操作：不带 WHERE 会更新所有行！ +UPDATE users SET age = 0; -- 慎用！ +``` + +#### **DELETE：删除数据** + +```sql +-- 删除指定行 +DELETE FROM users WHERE id = 1; + +-- ⚠️ 危险操作：不带 WHERE 会删除所有数据！ +DELETE FROM users; -- 慎用！ +``` + +::: warning 💡 最佳实践 +- 先用 `SELECT` 验证 WHERE 条件是否正确 +- 再用 `UPDATE/DELETE` 执行操作 +- 生产环境务必加 `LIMIT` 限制影响行数 +::: + +--- + +## 3. SELECT 进阶：JOIN、GROUP BY、子查询 + +当数据分布在多个表中时，我们需要更强大的查询能力。 + +### 3.1 JOIN：连接多个表 + +**场景**：一个电商系统有两个表： +- `users`（用户表）：id, name, email +- `orders`（订单表）：order_id, user_id, amount + +如何查询"每个用户的订单总金额"？ + +#### **INNER JOIN：只返回匹配的行** + +```sql +SELECT users.name, SUM(orders.amount) as total +FROM users +INNER JOIN orders ON users.id = orders.user_id +GROUP BY users.id; +``` + +**结果**：只显示有订单的用户 + +#### **LEFT JOIN：返回左表所有行** + +```sql +SELECT users.name, SUM(orders.amount) as total +FROM users +LEFT JOIN orders ON users.id = orders.user_id +GROUP BY users.id; +``` + +**结果**：显示所有用户，没有订单的用户 total 为 NULL + +::: tip 💡 如何选择 JOIN？ +- **INNER JOIN**：只要两边都有数据才需要（如：订单明细） +- **LEFT JOIN**：需要保留主表所有数据（如：用户列表 + 统计信息） +- **RIGHT JOIN**：需要保留从表所有数据（很少用） +- **FULL OUTER JOIN**：需要所有数据（MySQL 不支持，可用 UNION 实现） +::: + +### 3.2 GROUP BY：分组统计 + +**场景**：统计每个部门的平均工资。 + +```sql +SELECT department, AVG(salary) as avg_salary, COUNT(*) as count +FROM employees +GROUP BY department +HAVING AVG(salary) > 10000; -- HAVING 过滤分组后的结果 +``` + +**注意**： +- `WHERE` 过滤行（在 GROUP BY 之前） +- `HAVING` 过滤分组（在 GROUP BY 之后） + +### 3.3 子查询：查询嵌套查询 + +**场景**：查找工资高于平均工资的员工。 + +```sql +-- 方式一：WHERE 子查询 +SELECT name, salary +FROM employees +WHERE salary > (SELECT AVG(salary) FROM employees); + +-- 方式二：FROM 子查询（派生表） +SELECT dept_name, avg_salary +FROM ( + SELECT department, AVG(salary) as avg_salary + FROM employees + GROUP BY department +) as dept_avg +WHERE avg_salary > 10000; +``` + +::: tip 💡 子查询 vs JOIN +- **子查询**：逻辑清晰，但性能较差（每个子查询都会执行一次） +- **JOIN**：性能更好，但需要理解连接逻辑 +- **最佳实践**：优先使用 JOIN，必要时用子查询 +::: + +--- + +## 4. 索引原理：让查询快起来 + +### 4.1 为什么需要索引？ + +**场景**：在一个 100 万行的用户表中，查找 `id = 123456` 的用户。 + +**没有索引**： +- 数据库需要逐行扫描，最多比较 100 万次 +- 时间复杂度：O(n) + +**有索引**： +- 数据库通过 B+ 树快速定位，只需比较 log₂(100万) ≈ 20 次 +- 时间复杂度：O(log n) + +### 4.2 用图书馆来类比 + +| 概念 | 图书馆 | 数据库 | +| :--- | :--- | :--- | +| **数据** | 书籍 | 表的行 | +| **索引** | 目录卡片 | B+ 树 | +| **查询** | 按书名找书 | 按 WHERE 条件找行 | +| **无索引** | 逐排书架找 | 全表扫描 | +| **有索引** | 查目录定位 | 索引查找 | + +### 4.3 索引的可视化演示 + +👇 **动手试试看**：在 SqlDemo 组件的"索引"标签页查看无索引 vs 有索引的对比： + + + +### 4.4 索引的使用建议 + +| 场景 | 是否建索引 | 说明 | +| :--- | :--- | :--- | +| **WHERE 条件** | 是 | 如 `WHERE user_id = 1` | +| **JOIN 连接** | 是 | 如 `JOIN ON user_id` | +| **ORDER BY 排序** | 是 | 如 `ORDER BY created_at` | +| **低选择性列** | 否 | 如性别（只有男/女） | +| **频繁更新的列** | 谨慎 | 索引会降低写入性能 | +| **小表** | 否 | 数据量小不需要索引 | + +**创建索引**： +```sql +-- 单列索引 +CREATE INDEX idx_user_id ON orders(user_id); + +-- 复合索引（最左前缀原则） +CREATE INDEX idx_user_status ON orders(user_id, status); + +-- 唯一索引 +CREATE UNIQUE INDEX idx_email ON users(email); +``` + +::: tip 💡 索引的代价 +- **空间**：每个索引都是额外的存储空间 +- **时间**：INSERT/UPDATE/DELETE 需要更新索引，降低写入速度 +- **建议**：只在查询频繁、更新少的列上建索引 +::: + +--- + +## 5. 事务 ACID：保证数据一致性 + +### 5.1 什么是事务？ + +**事务**（Transaction）是一组 SQL 操作，要么全部成功，要么全部失败。 + +**经典案例**：银行转账 + +```sql +BEGIN; -- 开始事务 + +-- 账户 A 扣款 100 元 +UPDATE accounts SET balance = balance - 100 WHERE user_id = 1; + +-- 账户 B 加款 100 元 +UPDATE accounts SET balance = balance + 100 WHERE user_id = 2; + +COMMIT; -- 提交事务（如果中间出错，自动 ROLLBACK） +``` + +如果第二步失败（比如账户 B 不存在），整个事务会回滚，账户 A 不会被扣款。 + +### 5.2 ACID 四大特性 + +👇 **动手试试看**：在 SqlDemo 组件的"事务"标签页查看 ACID 可视化： + + + +#### **A - Atomicity（原子性）** +- **含义**：事务中的操作要么全部成功，要么全部失败 +- **类比**：转账要么同时成功，要么同时失败，不会出现"扣款了但没到账"的情况 +- **实现**：Undo Log（回滚日志） + +#### **C - Consistency（一致性）** +- **含义**：事务前后数据库状态一致，满足所有约束 +- **类比**：转账前后总金额不变（A 余额 + B 余额 = 总金额） +- **实现**：应用层约束 + 数据库约束 + +#### **I - Isolation（隔离性）** +- **含义**：并发事务之间互不干扰 +- **类比**：两个用户同时转账，不会相互影响 +- **实现**：锁机制 + MVCC（多版本并发控制） + +#### **D - Durability（持久性）** +- **含义**：事务提交后，永久保存，即使系统故障 +- **类比**：转账成功后，断电也不会丢失记录 +- **实现**：Redo Log（重做日志） + +### 5.3 事务隔离级别 + +| 隔离级别 | 脏读 | 不可重复读 | 幻读 | 性能 | 适用场景 | +| :--- | :--- | :--- | :--- | :--- | :--- | +| **READ UNCOMMITTED** | 是 | 是 | 是 | 高 | 几乎不用 | +| **READ COMMITTED** | 否 | 是 | 是 | 中 | 大多数数据库默认 | +| **REPEATABLE READ** | 否 | 否 | 是 | 低 | MySQL 默认 | +| **SERIALIZABLE** | 否 | 否 | 否 | 最低 | 金融级要求 | + +**设置隔离级别**： +```sql +-- 查看 +SELECT @@transaction_isolation; + +-- 设置 +SET TRANSACTION ISOLATION LEVEL READ COMMITTED; +``` + +::: tip 💡 如何选择隔离级别？ +- **默认使用 READ COMMITTED**：避免脏读，性能可接受 +- **金融场景**：使用 SERIALIZABLE 或 REPEATABLE READ +- **分析场景**：可降低到 READ UNCOMMITTED 提高性能 +::: + +--- + +## 6. SQL 注入：安全的警惕性 + +### 6.1 什么是 SQL 注入？ + +**SQL 注入**是一种常见的安全漏洞，攻击者通过构造恶意的输入，篡改 SQL 语句。 + +**示例**：一个登录接口 + +```sql +-- 正常 SQL +SELECT * FROM users WHERE username = 'admin' AND password = '123456'; + +-- 攻击者输入用户名：admin' -- +-- 拼接后的 SQL +SELECT * FROM users WHERE username = 'admin' --' AND password = '123456'; +-- ↑ 注释掉后面的密码验证，直接登录成功！ +``` + +**更危险的攻击**： + +```sql +-- 用户名输入：admin'; DROP TABLE users; -- +-- 拼接后的 SQL +SELECT * FROM users WHERE username = 'admin'; DROP TABLE users; --' +``` + +### 6.2 如何防御？ + +#### **方法一：参数化查询（推荐）** + +```python +# ❌ 错误：直接拼接字符串（危险！） +sql = f"SELECT * FROM users WHERE username = '{username}'" +cursor.execute(sql) + +# ✅ 正确：使用参数化查询（安全） +sql = "SELECT * FROM users WHERE username = %s" +cursor.execute(sql, (username,)) +``` + +#### **方法二：ORM 框架** + +```python +# Django ORM +user = User.objects.get(username=username) + +# SQLAlchemy +user = session.query(User).filter(User.username == username).first() +``` + +#### **方法三：输入验证** + +```python +# 限制用户名只能包含字母、数字、下划线 +import re +if not re.match(r'^\w+$', username): + raise ValueError('Invalid username') +``` + +::: warning 💡 防御 SQL 注入的黄金法则 +1. **永远不要相信用户输入** +2. **永远使用参数化查询或 ORM** +3. **永远不要拼接 SQL 字符串** +4. **最小权限原则**：数据库用户只给必要权限 +::: + +--- + +## 7. 最佳实践 + +### 7.1 查询优化 + +| 优化技巧 | 说明 | 示例 | +| :--- | :--- | :--- | +| **避免 SELECT \*** | 只查询需要的列 | `SELECT name, email FROM users` | +| **使用 LIMIT** | 限制结果数量 | `SELECT * FROM users LIMIT 10` | +| **索引覆盖** | 查询条件使用索引列 | `WHERE indexed_col = 1` | +| **避免子查询** | 用 JOIN 替代子查询 | 见上文对比 | +| **批量操作** | 减少数据库往返 | `INSERT INTO ... VALUES (...), (...), (...)` | +| **分页查询** | 大数据量分页 | `SELECT * FROM users LIMIT 10 OFFSET 20` | + +### 7.2 命名规范 + +| 类型 | 规范 | 示例 | +| :--- | :--- | :--- | +| **表名** | 小写 + 下划线 | `user_profiles`, `order_items` | +| **列名** | 小写 + 下划线 | `created_at`, `user_id` | +| **索引名** | `idx_表名_列名` | `idx_users_email` | +| **外键名** | `fk_表名_列名` | `fk_orders_user_id` | +| **主键名** | 统一使用 `id` | 无 | + +### 7.3 数据库设计 + +| 设计原则 | 说明 | 示例 | +| :--- | :--- | :--- | +| **规范化** | 消除数据冗余 | 第三范式（3NF） | +| **反规范化** | 适当冗余提高性能 | 在订单表冗余用户姓名 | +| **主键选择** | 优先使用自增 ID | `id BIGINT AUTO_INCREMENT` | +| **时间字段** | 统一使用 DATETIME | `created_at DATETIME` | +| **软删除** | 用 `is_deleted` 标记 | 不真删除，便于恢复 | + +--- + +## 8. 用 AI 辅助编写 SQL + +AI 可以帮助你快速编写复杂的 SQL 查询。关键在于提供清晰的表结构和业务需求。 + +### 8.1 提示词模板 + +``` +你是一位资深的数据库工程师，精通 SQL 查询优化。请帮我编写 SQL 查询。 + +## 数据库表结构 +[提供表的 CREATE TABLE 语句或字段说明] + +## 业务需求 +[描述你想要查询的数据，例如： +- 统计每个月的订单总金额 +- 查找购买过商品 A 和商品 B 的用户 +- 计算用户的留存率] + +## 要求 +1. 使用标准 SQL 语法（兼容 MySQL 8.0） +2. 注释关键逻辑 +3. 考虑性能优化（索引、JOIN 顺序） +4. 提供多种实现方案（如子查询 vs JOIN） + +## 输出格式 +### SQL 查询 +\`\`\`sql +[SQL 语句] +\`\`\` + +### 逻辑说明 +[解释查询的逻辑和优化思路] +``` + +### 8.2 实战示例：复杂统计查询 + +**输入提示词**： + +``` +你是一位资深的数据库工程师，精通 SQL 查询优化。请帮我编写 SQL 查询。 + +## 数据库表结构 + +```sql +-- 用户表 +CREATE TABLE users ( + id BIGINT PRIMARY KEY AUTO_INCREMENT, + name VARCHAR(50), + created_at DATETIME +); + +-- 订单表 +CREATE TABLE orders ( + id BIGINT PRIMARY KEY AUTO_INCREMENT, + user_id BIGINT, + amount DECIMAL(10, 2), + status ENUM('pending', 'paid', 'shipped', 'completed', 'cancelled'), + created_at DATETIME, + FOREIGN KEY (user_id) REFERENCES users(id) +); + +-- 订单详情表 +CREATE TABLE order_items ( + id BIGINT PRIMARY KEY AUTO_INCREMENT, + order_id BIGINT, + product_id BIGINT, + quantity INT, + price DECIMAL(10, 2), + FOREIGN KEY (order_id) REFERENCES orders(id) +); + +-- 商品表 +CREATE TABLE products ( + id BIGINT PRIMARY KEY AUTO_INCREMENT, + name VARCHAR(100), + category VARCHAR(50) +); +``` + +## 业务需求 +1. 统计每个月的订单总金额和订单数量 +2. 查找购买过商品 A 和商品 B 的用户 +3. 计算用户复购率（有多少用户下了多个订单） + +## 要求 +1. 使用标准 SQL 语法（兼容 MySQL 8.0） +2. 注释关键逻辑 +3. 考虑性能优化 +``` + +**AI 输出示例**： + +```sql +-- 需求 1：统计每个月的订单总金额和订单数量 +SELECT + DATE_FORMAT(created_at, '%Y-%m') AS month, + COUNT(*) AS order_count, + SUM(amount) AS total_amount +FROM orders +WHERE status IN ('paid', 'shipped', 'completed') -- 只统计有效订单 +GROUP BY DATE_FORMAT(created_at, '%Y-%m') +ORDER BY month DESC; + +-- 需求 2：查找购买过商品 A 和商品 B 的用户 +-- 方案一：INTERSECT（MySQL 不支持，用 IN 替代） +SELECT DISTINCT user_id +FROM orders o +JOIN order_items oi ON o.id = oi.order_id +JOIN products p ON oi.product_id = p.id +WHERE p.name IN ('商品 A', '商品 B') +GROUP BY user_id +HAVING COUNT(DISTINCT p.name) = 2; -- 确保同时买了两个商品 + +-- 方案二：自连接（性能更好） +SELECT + oa.user_id +FROM orders oa +JOIN order_items oia ON oa.id = oia.order_id +JOIN products pa ON oia.product_id = pa.id +JOIN order_items oib ON oa.id = oib.order_id -- 同一个订单 +JOIN products pb ON oib.product_id = pb.id +WHERE pa.name = '商品 A' AND pb.name = '商品 B'; + +-- 需求 3：计算用户复购率 +WITH user_order_count AS ( + SELECT + user_id, + COUNT(*) AS order_count + FROM orders + WHERE status IN ('paid', 'shipped', 'completed') + GROUP BY user_id +) +SELECT + COUNT(CASE WHEN order_count >= 2 THEN 1 END) AS repeat_users, + COUNT(*) AS total_users, + ROUND(COUNT(CASE WHEN order_count >= 2 THEN 1 END) * 100.0 / COUNT(*), 2) AS repeat_rate +FROM user_order_count; +``` + +### 8.3 AI 辅助的注意事项 + +| 注意点 | 说明 | +| :--- | :--- | +| **提供完整上下文** | 表结构、索引、数据量都要说清楚 | +| **明确性能要求** | 是否需要优化、数据量大小 | +| **验证 SQL 语法** | AI 生成的 SQL 可能有小错误，需要测试 | +| **理解执行计划** | 用 `EXPLAIN` 查看查询是否使用了索引 | +| **分步实现** | 复杂查询可以拆分成多个简单查询 | + +::: tip 💡 追问技巧 +- "请提供另一种实现方案（如用 JOIN 替代子查询）" +- "请分析这条查询的性能瓶颈" +- "请添加索引建议" +- "请解释每个步骤的逻辑" +::: + +--- + +## 名词速查表 + +| 名词 | 英文 | 解释 | +| :--- | :--- | :--- | +| **SQL** | Structured Query Language | 结构化查询语言，与数据库对话的标准语言 | +| **数据库** | Database | 存储和管理数据的仓库 | +| **表** | Table | 数据的二维表格，类似 Excel | +| **行** | Row | 表中的一条记录 | +| **列** | Column | 表中的一个字段 | +| **主键** | Primary Key | 唯一标识一行的字段（如 id） | +| **外键** | Foreign Key | 关联其他表的字段 | +| **索引** | Index | 加速查询的数据结构（B+ 树） | +| **事务** | Transaction | 一组要么全成功、要么全失败的 SQL 操作 | +| **ACID** | Atomicity, Consistency, Isolation, Durability | 事务的四大特性 | +| **JOIN** | Join | 连接多个表的查询操作 | +| **子查询** | Subquery | 嵌套在另一个查询中的查询 | +| **聚合函数** | Aggregate Function | SUM, AVG, COUNT, MAX, MIN | +| **分组** | Group By | 按字段分组统计 | +| **SQL 注入** | SQL Injection | 通过输入篡改 SQL 语句的攻击方式 | +| **规范化** | Normalization | 消除数据冗余的设计原则 | +| **反规范化** | Denormalization | 适当冗余提高性能的设计 | +| **执行计划** | Execution Plan | 数据库执行 SQL 的详细步骤 | +| **B+ 树** | B+ Tree | 索引的底层数据结构 | +| **MVCC** | Multi-Version Concurrency Control | 多版本并发控制，实现事务隔离 | +| **脏读** | Dirty Read | 读取未提交的数据 | +| **不可重复读** | Non-Repeatable Read | 同一事务两次读取结果不同 | +| **幻读** | Phantom Read | 同一事务两次读取结果集不同 | +| **隔离级别** | Isolation Level | 事务隔离的程度（READ UNCOMMITTED/READ COMMITTED/REPEATABLE READ/SERIALIZABLE） |