# Python 3.12 开发最佳实践 - 文档索引
> 综合指南：Python 3.12 现代开发的最佳实践、工具和模式
>
> 最后更新：2025年1月
---
## 📚 文档目录
### 01. 新特性
Python 3.12 的核心语言改进和新功能。
- [PEP 695: 泛型语法](./01_新特性/PEP695_泛型语法.md) - 更简洁的泛型类和函数
- [PEP 701: F-String 增强](./01_新特性/PEP701_FString增强.md) - 更灵活的 f-string 语法
- [PEP 698: Override 装饰器](./01_新特性/PEP698_Override装饰器.md) - 明确标记重写方法
- [改进的错误消息](./01_新特性/改进的错误消息.md) - 更有帮助的错误提示
- [性能改进](./01_新特性/性能改进.md) - ~5% 整体性能提升
- [PEP 669: 监控 API](./01_新特性/PEP669_监控API.md) - 低影响监控和调试
- [PEP 684: 子解释器](./01_新特性/PEP684_子解释器.md) - 独立 GIL 的子解释器
- [Linux Perf 支持](./01_新特性/LinuxPerf支持.md) - 系统级性能分析
### 02. 项目结构
Python 项目的组织和布局最佳实践。
- [扁平布局](./02_项目结构/扁平布局.md) - 推荐的项目结构
- [目录组织原则](./02_项目结构/目录组织原则.md) - 按功能分组的组织策略
- [命名约定](./02_项目结构/命名约定.md) - 文件、类、函数命名规范
- [特殊文件](./02_项目结构/特殊文件.md) - `__init__.py`, `py.typed` 等
- [pyproject.toml 配置](./02_项目结构/pyproject.toml配置.md) - 项目配置文件
### 03. 依赖管理
使用 UV 进行现代包管理。
- [UV 简介](./03_依赖管理/UV简介.md) - 快速、现代的包管理器
- [UV 高级功能](./03_依赖管理/UV高级功能.md) - 工作区、锁文件、发布
- [虚拟环境最佳实践](./03_依赖管理/虚拟环境最佳实践.md) - 环境隔离和管理
### 04. 类型提示
静态类型检查和类型提示最佳实践。
- [基本类型提示](./04_类型提示/基本类型提示.md) - 基础类型注解
- [高级类型提示](./04_类型提示/高级类型提示.md) - 协议、泛型、高级特性
- [Basedpyright 配置](./04_类型提示/Basedpyright配置.md) - 现代类型检查器
### 05. 代码质量
使用 Ruff 进行代码质量保证。
- [Ruff 简介](./05_代码质量/Ruff简介.md) - 一体化 lint 和格式化工具
- [Ruff 配置](./05_代码质量/Ruff配置.md) - 详细配置选项
- [Pre-Commit 钩子](./05_代码质量/PreCommit钩子.md) - 自动代码质量检查
### 06. 测试
使用 Pytest 进行全面测试。
- [Pytest 简介](./06_测试/Pytest简介.md) - Python 测试的事实标准
- [Fixtures 使用](./06_测试/Fixtures使用.md) - 测试设置和拆卸
- [参数化测试](./06_测试/参数化测试.md) - 高效的测试参数化
### 07. 异步编程
Asyncio 和异步编程模式。
- [Asyncio 基础](./07_异步编程/Asyncio基础.md) - 异步编程入门
- [Worker Pool 模式](./07_异步编程/WorkerPool模式.md) - 并发任务处理
### 08. 性能优化
性能分析和优化技术。
- [性能分析工具](./08_性能优化/性能分析工具.md) - cProfile, line_profiler, memory_profiler
- [通用优化技术](./08_性能优化/通用优化技术.md) - 实用优化模式
### 09. 安全
OWASP 安全最佳实践。
- [OWASP #1: 注入攻击](./09_安全/OWASP01_注入攻击.md) - SQL 注入防护
- [OWASP #2: 破损的认证](./09_安全/OWASP02_破损的认证.md) - 安全密码处理
- [OWASP #3: 敏感数据暴露](./09_安全/OWASP03_敏感数据暴露.md) - 机密管理和加密
---
## 🚀 快速开始
1. **创建新项目**
```bash
uv init my-project
cd my-project
uv venv
source .venv/bin/activate
```
2. **添加依赖**
```bash
uv add requests pydantic
uv add --dev pytest ruff basedpyright
```
3. **配置工具**
- 复制 [pyproject.toml 配置](./02_项目结构/pyproject.toml配置.md)
- 设置 [Ruff](./05_代码质量/Ruff配置.md) 和 [Basedpyright](./04_类型提示/Basedpyright配置.md)
4. **开始编码**
- 遵循 [命名约定](./02_项目结构/命名约定.md)
- 使用 [类型提示](./04_类型提示/基本类型提示.md)
- 编写 [测试](./06_测试/Pytest简介.md)
---
## 📖 推荐学习路径
### 初学者
1. [扁平布局](./02_项目结构/扁平布局.md) - 项目结构
2. [UV 简介](./03_依赖管理/UV简介.md) - 包管理
3. [基本类型提示](./04_类型提示/基本类型提示.md) - 类型注解
4. [Pytest 简介](./06_测试/Pytest简介.md) - 测试基础
### 中级开发者
1. [PEP 695: 泛型语法](./01_新特性/PEP695_泛型语法.md) - Python 3.12 新特性
2. [高级类型提示](./04_类型提示/高级类型提示.md) - 高级类型系统
3. [Ruff 配置](./05_代码质量/Ruff配置.md) - 代码质量工具
4. [Asyncio 基础](./07_异步编程/Asyncio基础.md) - 异步编程
### 高级开发者
1. [性能改进](./01_新特性/性能改进.md) - Python 3.12 性能
2. [性能分析工具](./08_性能优化/性能分析工具.md) - 性能优化
3. [Worker Pool 模式](./07_异步编程/WorkerPool模式.md) - 高级异步模式
4. [OWASP 安全最佳实践](./09_安全/OWASP01_注入攻击.md) - 安全编程
---
## 🛠️ 工具链推荐
| 包管理 | UV | [UV 简介](./03_依赖管理/UV简介.md) |
| 类型检查 | Basedpyright | [Basedpyright 配置](./04_类型提示/Basedpyright配置.md) |
| Lint & 格式化 | Ruff | [Ruff 简介](./05_代码质量/Ruff简介.md) |
| 测试 | Pytest | [Pytest 简介](./06_测试/Pytest简介.md) |
| 性能分析 | cProfile | [性能分析工具](./08_性能优化/性能分析工具.md) |
---
## 📝 贡献
欢迎为本文档做出贡献！如果您发现错误或有改进建议，请提交 Issue 或 Pull Request。
---
## 📄 许可
本文档遵循 CC BY-SA 4.0 许可协议。
---
**文档版本**: 1.0.0
**最后更新**: 2025年1月
**Python 版本**: 3.12+