FastAPI文档代码示例语法升级指南

FastAPI项目近期对其文档系统中的代码示例引入语法进行了重大升级，旨在简化维护流程并提升多版本Python支持能力。本文将详细介绍新旧语法对比、迁移策略及最佳实践。

新旧语法对比

旧版语法采用Markdown代码块与特殊注释的组合方式：

```Python hl_lines="3"
{!../../docs_src/first_steps/tutorial001.py!}
```

新版语法采用更简洁的内联格式：

{* ../../docs_src/first_steps/tutorial001.py hl[3] *}

主要改进点包括：

1. 使用{*和*}替代{!和!}
2. 移除冗余的代码块标记（Python）
3. 行高亮语法从hl_lines="3"简化为hl[3]
4. 支持更灵活的行号指定方式

行高亮语法升级

新版支持多种高亮模式：

单行高亮

hl[3]      // 高亮第3行

多行高亮

hl[3,5,7]  // 高亮3、5、7行

范围高亮

hl[3:7]    // 高亮3-7行

混合模式

hl[2,4:6,8]  // 高亮2行、4-6行、8行

多版本Python支持

旧版需要显式声明每个Python版本：

//// tab | Python 3.9+
```Python hl_lines="4  8  12"
{!> ../../docs_src/security/tutorial006_an_py39.py!}
```
////

新版只需指定主版本文件：

{* ../../docs_src/security/tutorial006_an_py39.py hl[4,8,12] *}

系统会自动处理：

1. 生成版本切换标签页
2. 包含所有变体文件
3. 保持原有高亮逻辑

部分代码包含

对于只需展示部分代码的场景：

旧版语法：

```Python hl_lines="7"
{!> ../../docs_src/separate_openapi_schemas/tutorial001_py310.py[ln:1-7]!}

# Code below omitted 👇
```

新版语法：

{* ../../docs_src/separate_openapi_schemas/tutorial001_py310.py ln[1:7] hl[7] *}

改进包括：

1. 使用ln[1:7]指定行范围
2. 自动生成省略注释
3. 支持多范围选择（如ln[1:3,5:7]）

迁移建议

1. 单文件处理：建议每个文档页面单独提交PR
2. 版本控制：优先保留最高Python版本的文件引用
3. 语法验证：迁移后检查预览效果
4. 复杂场景：不符合标准模式的案例可暂缓处理

技术优势

新语法系统为FastAPI文档带来显著改进：

1. 维护简化：减少50%以上的样板代码
2. 一致性增强：统一所有代码示例的处理逻辑
3. 可扩展性：为未来功能（如交互式示例）奠定基础
4. 测试保障：所有示例仍保持CI验证机制

这次升级体现了FastAPI项目对文档质量的持续追求，使开发者能够更高效地获取准确、可靠的代码示例。