update docs

Author: wu-clan

docs/.vuepress/theme.ts

@@ -11,19 +11,23 @@ export const myTheme: Theme = plumeTheme({
     docsRepo: 'https://github.com/fastapi-practices/fastapi_best_architecture_docs',
     docsBranch: 'master',
     docsDir: 'docs',
-    blog: {
-        include: ['blog/**/*.md'],
-    },
+    collections: [
+        {
+            type: 'post',
+            dir: 'blog',
+            title: '博客',
+            include: ['**/*.md'],
+        }
+    ],
     profile: {
-        name: 'null',
+        name: 'wu-clan',
         description: 'An open-source enthusiast, creator and contributor',
         avatar: 'https://wu-clan.github.io/picx-images-hosting/avatar.gif',
         location: '郑州，河南',
         organization: 'FastAPI Practices',
         circle: true,
         layout: 'right',
     },
-    notes: false,
     bulletin: myBulletin,
     sidebar: mySidebar,
     sidebarScrollbar: false,

docs/README.md

@@ -53,6 +53,7 @@ config:
         icon: 🐳
         details: 提供 Docker compose 一键部署方案
   - type: custom
+title: .
 ---
 
 <script setup lang="ts">

docs/blog/custom_exception.md renamed to docs/blog/custom-exception.md

@@ -0,0 +1,108 @@
+---
+title: Typing Cast：静态类型安全的“逃生舱”?
+createTime: 2025-9-11 12:30
+tags:
+  - Typing
+---
+
+在 Python 3.5 引入类型提示以来，渐进式类型系统让我们的代码更易维护、更易协作。但类型检查器有时太“聪明”了，会因为动态数据或第三方库而迷失方向。
+
+`typing.cast` 就像一个“类型声明器”，帮你明确告诉检查器：“嘿，这个值就是这个类型，别多想了！”
+
+## 什么是 typing.cast
+
+`typing.cast` 是 Python 标准库 `typing` 模块中的一个辅助函数。它的核心作用是**在静态类型检查阶段“强制”指定一个值的类型**
+，但在运行时，它什么都不做——只是原封不动地返回输入的值。 这设计非常巧妙：它确保了零运行时开销，同时提升了代码的静态安全性
+
+简单来说：
+
+- **静态时**：类型检查器（如 mypy）会认为返回值就是你指定的类型，从而正确推断后续代码
+- **运行时**：Python 继续它的鸭子类型哲学，一切照旧
+
+这不同于真正的类型转换（如 `int("123")`），它更像是一个“类型断言”，专为类型提示生态设计
+
+## 如何使用 typing.cast
+
+使用 `typing.cast` 非常简单。它的签名是：
+
+```python
+from typing import cast
+
+result = cast(目标类型, 值)
+```
+
+- `目标类型`：可以是任何有效的类型提示，如 `int`、`List[str]`、`Optional[Dict[str, int]]` 等
+- `值`：你要“转换”的对象，运行时它不会变
+
+让我们通过几个例子来看看它怎么玩转类型提示。
+
+### 示例 1：处理 Any 类型
+
+`Any` 类型是类型提示中的“万金油”，但它会让类型检查器变得宽松。假如你从外部 API 获取数据，知道它其实是 `List[int]`，但检查器只看到
+`Any`：
+
+```python
+from typing import Any, cast, List
+
+def process_scores(data: Any) -> List[int]:
+    # 假设我们已经验证了 data 是整数列表
+    scores: List[int] = cast(List[int], data)
+    return [score * 2 for score in scores]  # 现在检查器知道 scores 是 List[int]，不会报错
+
+# 使用
+raw_data = [1, 2, 3]  # 来自 API 的数据
+doubled = process_scores(raw_data)
+```
+
+没有 `cast`，mypy 可能会抱怨 `scores` 的类型不明，导致后续列表推导式报错
+
+### 示例 2：从 object 窄化类型
+
+有时函数参数是 `object`（Python 的万能基类），但你知道具体类型：
+
+```python
+from typing import cast
+
+def get_length(item: object) -> int:
+    # 假设 item 已被检查为 str
+    length: int = len(cast(str, item))  # 告诉检查器：item 是 str
+    return length
+
+# 使用
+result = get_length("hello")  # 运行正常，检查器也满意
+```
+
+### 示例 3：第三方库集成
+
+集成像 `requests` 这样的库时，返回值往往是 `Any`。用 `cast` 可以快速窄化：
+
+```python
+import requests
+from typing import cast, Dict, Any
+
+response = requests.get("https://api.example.com/data")
+data: Dict[str, int] = cast(Dict[str, int], response.json())  # 假设我们知道 JSON 是这个结构
+total = sum(data.values())  # 检查器现在知道 data 是 Dict[str, int]
+```
+
+这些例子展示了 `cast` 如何在不改动运行逻辑的情况下，提升代码的可读性和工具支持
+
+## 实际应用场景
+
+`typing.cast` 最常出现在这些地方：
+
+- **动态数据处理**：如 JSON 解析、配置文件读取
+- **遗留代码迁移**：逐步添加类型提示时，桥接动态和静态部分
+- **低级 API**：如 C 扩展或网络协议解析，类型不明显
+- **测试与模拟**：mock 对象需要精确类型
+
+在大型项目中，它能减少类型检查器的噪音，让开发者专注于真正的问题
+
+## 注意事项
+
+`cast` 虽然强大，但也有风险：
+
+- **无运行时保护**：它不会验证类型，如果你的假设是错误的（如 `cast(int, "abc")`），运行时会炸锅
+- **滥用风险**：过度使用会隐藏真实类型错误，降低代码质量。记住，它是“逃生舱”，不是日常工具
+- **最佳实践**：优先用条件检查（如 `isinstance`）或更精确的类型提示。只有当检查器“顽固”时，才祭出 `cast`。另外，从 Python 3.11
+  开始，还有 `typing.assert_type` 可以辅助验证，但它也只在静态阶段生效

docs/blog/header_token.md renamed to docs/blog/header-token.md

@@ -1,6 +1,6 @@
 {
   "name": "fastapi_best_architecture_docs",
-  "version": "1.8.1",
+  "version": "1.8.2",
   "description": "fastapi_best_architecture 官方文档",
   "main": "index.js",
   "scripts": {
@@ -21,14 +21,14 @@
     "@vuepress/plugin-baidu-analytics": "2.0.0-rc.112",
     "@vuepress/plugin-llms": "2.0.0-rc.112",
     "@vuepress/plugin-umami-analytics": "2.0.0-rc.112",
-    "vue": "^3.5.21",
+    "vue": "^3.5.22",
     "vuepress": "2.0.0-rc.24",
-    "vuepress-theme-plume": "1.0.0-rc.164"
+    "vuepress-theme-plume": "1.0.0-rc.169"
   },
   "dependencies": {
-    "@iconify/json": "^2.2.386",
+    "@iconify/json": "^2.2.394",
     "@vueuse/core": "^12.8.2",
     "mermaid": "^11.12.0",
-    "swiper": "^11.2.10"
+    "swiper": "^12.0.2"
   }
 }