06 - Codex 最佳实践
从入门到精通:构建高效的 AI 辅助编程工作流
📋 本章目标
学完本章,你将能够:
- 掌握编写高质量提示词的技巧
- 建立高效的编程工作流
- 确保代码质量和安全
- 实现团队协作的最佳实践
✍️ 提示词工程
提示词的四个维度
好的提示词 = 清晰 + 具体 + 上下文 + 约束
1. 清晰(Clarity)
└─ 明确说明要做什么
2. 具体(Specificity)
└─ 提供详细的要求和限制
3. 上下文(Context)
└─ 给出必要的背景信息
4. 约束(Constraints)
└─ 明确技术栈、风格等限制
提示词模板
模板 1:功能开发
【功能描述】
简洁明确地描述要实现的功能
【技术要求】
- 编程语言:[Python/JavaScript/...]
- 框架:[React/Django/...]
- 版本:[Python 3.10/Node 18/...]
【输入输出】
输入:
- 参数1:类型,说明
- 参数2:类型,说明
输出:
- 返回值类型和格式
【特殊要求】
- 错误处理:如何处理异常
- 性能要求:响应时间/内存限制
- 安全考虑:输入验证/权限检查
【示例】
输入示例:xxx
输出示例:xxx
【代码风格】
- 遵循 [PEP 8/Airbnb Style/...]
- 添加类型注解
- 包含详细注释
实际示例:
【功能描述】
创建一个异步函数,从多个API并行获取数据,并聚合结果
【技术要求】
- 编程语言:Python 3.10+
- 使用 asyncio 和 aiohttp
- 使用类型注解
【输入输出】
输入:
- urls: List[str] - API URL 列表
- timeout: int - 超时时间(秒),默认10
输出:
- Dict[str, Any] - 键为URL,值为响应数据或错误信息
【特殊要求】
- 错误处理:单个API失败不影响其他
- 超时控制:每个请求独立超时
- 并发限制:最多同时10个请求
【示例】
输入:
urls = [
"https://api1.com/data",
"https://api2.com/data"
]
timeout = 5
输出:
{
"https://api1.com/data": {"status": "success", "data": {...}},
"https://api2.com/data": {"status": "error", "error": "Timeout"}
}
【代码风格】
- 遵循 PEP 8
- 添加 docstring
- 使用 typing 模块的类型注解
模板 2:代码优化
【当前代码】
```[language]
[粘贴现有代码]
【问题描述】
- 性能瓶颈:[具体问题]
- 可读性问题:[具体问题]
- 维护性问题:[具体问题]
【优化目标】
- 主要目标:[性能/可读性/可维护性]
- 次要目标:[...]
【约束条件】
- 保持功能不变
- 兼容现有接口
- 不引入新的依赖(如适用)
【期望输出】
- 优化后的代码
- 优化说明
- 性能对比(如适用)
**实际示例**:
【当前代码】
def process_users(users):
result = []
for user in users:
if user['age'] > 18:
name = user['name'].upper()
email = user['email'].lower()
result.append({
'name': name,
'email': email,
'adult': True
})
return result
【问题描述】
- 性能问题:处理大量用户时很慢
- 可读性问题:逻辑混在一起
- 没有类型注解和错误处理
【优化目标】
- 主要:提升性能(处理10万用户)
- 次要:提高可读性,添加错误处理
【约束条件】
- 保持函数签名
- Python 3.8+
- 不引入外部依赖
【期望输出】
- 优化后的代码(使用列表推导式等)
- 性能提升说明
- 添加类型注解和错误处理
#### 模板 3:Bug 修复
【错误现象】 描述出现的错误或异常行为
【错误代码】
[粘贴有问题的代码]
【错误信息】
[粘贴完整的错误堆栈]
【预期行为】 描述正确的行为应该是什么
【环境信息】
- 语言版本:[...]
- 依赖版本:[...]
- 操作系统:[...]
【已尝试的方案】
- [方案1] - 结果:[...]
- [方案2] - 结果:[...]
### 少样本学习(Few-shot Learning)
#### 示例驱动生成
【任务】 创建数据验证函数
【示例 1】 输入:邮箱字符串 功能:验证邮箱格式
def validate_email(email: str) -> bool: """验证邮箱格式""" import re pattern = r'^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+.[a-zA-Z]{2,}$' return bool(re.match(pattern, email))
【示例 2】 输入:手机号字符串 功能:验证中国手机号格式
def validate_phone(phone: str) -> bool: """验证中国手机号格式""" import re pattern = r'^1[3-9]\d{9}$' return bool(re.match(pattern, phone))
【现在请创建】 输入:身份证号字符串 功能:验证中国身份证号格式(18位)
AI 会模仿上述模式生成类似结构的代码
### 思维链(Chain of Thought)
不好的提示: "优化这个算法"
好的提示(包含思维链): "请分析这个算法:
- 首先识别算法的时间复杂度
- 找出主要的性能瓶颈
- 提出3种优化方案
- 比较各方案的优缺点
- 选择最佳方案并实现
- 分析优化后的复杂度"
---
## 🚀 工作流设计
### 日常编码工作流
#### 流程图
┌──────────────────────────────────────┐ │ 日常编码工作流 │ ├──────────────────────────────────────┤ │ │ │ 1. 📝 需求分析 │ │ └─ 明确要实现的功能 │ │ │ │ 2. 🤔 方案设计 │ │ └─ 与 AI 讨论技术方案 │ │ │ │ 3. ✍️ 代码生成 │ │ ├─ 让 AI 生成框架代码 │ │ └─ 人工审查和调整 │ │ │ │ 4. 🔍 代码审查 │ │ ├─ AI 审查代码质量 │ │ └─ 人工审查业务逻辑 │ │ │ │ 5. 🧪 测试 │ │ ├─ AI 生成测试用例 │ │ └─ 运行测试 │ │ │ │ 6. 📚 文档 │ │ └─ AI 生成文档和注释 │ │ │ │ 7. 🚀 提交 │ │ └─ Git commit & push │ │ │ └──────────────────────────────────────┘
#### 实际操作示例
**场景**:开发一个用户注册API
**Step 1:需求分析**
你的输入: "我需要创建一个用户注册API,需要考虑哪些方面?"
AI 输出:
- 数据验证(邮箱、密码强度)
- 密码加密存储
- 邮箱唯一性检查
- 发送验证邮件
- 错误处理
- 速率限制
- 日志记录
**Step 2:方案设计**
你的输入: "使用 FastAPI 实现,请给出技术方案"
AI 输出: 技术栈:
- FastAPI(web 框架)
- Pydantic(数据验证)
- bcrypt(密码加密)
- SQLAlchemy(数据库)
- Celery(异步任务,发送邮件)
架构设计: /api/auth/register ├─ 验证输入 ├─ 检查用户是否存在 ├─ 加密密码 ├─ 保存到数据库 └─ 触发邮件发送
**Step 3:代码生成**
你的输入: "实现这个 API,包含完整的错误处理和验证"
AI 生成完整代码(见下方)
**Step 4:代码审查**
你的输入: "审查这段代码,重点关注安全性"
AI 审查结果: ✅ 密码加密正确 ✅ SQL 注入防护 ⚠️ 建议添加请求频率限制 ⚠️ 建议添加邮箱格式二次验证 ❌ 缺少 CSRF 保护
**Step 5:测试**
你的输入: "生成完整的测试用例"
AI 生成 pytest 测试代码
### 代码审查工作流
#### AI 辅助代码审查检查清单
```yaml
代码质量:
- [ ] 命名是否清晰
- [ ] 代码是否简洁
- [ ] 是否有重复代码
- [ ] 注释是否充分
功能正确性:
- [ ] 是否实现了需求
- [ ] 边界情况是否处理
- [ ] 错误处理是否完善
性能:
- [ ] 是否有性能瓶颈
- [ ] 数据库查询是否优化
- [ ] 是否有内存泄漏
安全性:
- [ ] 输入验证
- [ ] SQL 注入防护
- [ ] XSS 防护
- [ ] 敏感信息保护
可维护性:
- [ ] 代码结构清晰
- [ ] 模块化设计
- [ ] 文档完整
- [ ] 易于测试
使用 AI 进行代码审查
def code_review_with_ai(code: str, focus: str = "all"):
"""使用 AI 进行代码审查"""
prompt = f"""
请审查以下代码,重点关注:{focus}
```
{code}
```
请按以下格式输出:
## 🎯 整体评价
[总体评价]
## ✅ 优点
- [优点1]
- [优点2]
## ⚠️ 问题
### 严重问题
- [问题1]
- 位置:[行号]
- 说明:[...]
- 建议:[...]
### 一般问题
- [问题2]
- 位置:[行号]
- 说明:[...]
- 建议:[...]
## 💡 优化建议
- [建议1]
- [建议2]
## 📝 改进后的代码
```[language]
[改进后的代码]
```
"""
return call_ai(prompt)
# 使用示例
review = code_review_with_ai(
code=my_code,
focus="安全性和性能"
)
print(review)
测试驱动开发工作流
TDD with AI
传统 TDD:
1. 写测试
2. 运行测试(失败)
3. 写代码
4. 运行测试(通过)
5. 重构
AI 辅助 TDD:
1. 描述需求 → AI 生成测试
2. 运行测试(失败)
3. 描述实现 → AI 生成代码
4. 运行测试(可能失败)
5. 与 AI 讨论问题 → 修复代码
6. 运行测试(通过)
7. AI 建议重构方案 → 重构
示例:
# Step 1:让 AI 生成测试
你的输入:
"""
功能:计算购物车总价
需求:
- 支持折扣
- 支持优惠券
- 满减活动
请生成测试用例
"""
# AI 生成测试
```python
def test_calculate_total_basic():
"""基本价格计算"""
cart = Cart()
cart.add_item(Item("Apple", 10.0, 2))
assert cart.calculate_total() == 20.0
def test_calculate_total_with_discount():
"""应用折扣"""
cart = Cart()
cart.add_item(Item("Apple", 10.0, 2))
cart.apply_discount(0.1) # 10% 折扣
assert cart.calculate_total() == 18.0
def test_calculate_total_with_coupon():
"""使用优惠券"""
cart = Cart()
cart.add_item(Item("Apple", 10.0, 2))
cart.apply_coupon(Coupon("SAVE5", 5.0))
assert cart.calculate_total() == 15.0
def test_calculate_total_full_price():
"""满减活动"""
cart = Cart()
cart.add_item(Item("Apple", 10.0, 10)) # 总计100
# 满100减20
assert cart.calculate_total() == 80.0
Step 2:让 AI 实现功能
你的输入: """ 根据上述测试用例,实现 Cart 类和相关逻辑 """
AI 生成实现代码...
---
## ✅ 质量保证
### 代码质量检查
#### 自动化检查流程
```bash
# 1. 代码风格检查
pylint your_code.py
flake8 your_code.py
# 2. 类型检查
mypy your_code.py
# 3. 安全检查
bandit your_code.py
# 4. 测试覆盖率
pytest --cov=your_module tests/
# 5. 复杂度分析
radon cc your_code.py
使用 AI 辅助质量检查
def ai_quality_check(code: str):
"""AI 辅助质量检查"""
checks = {
"代码风格": check_code_style(code),
"类型安全": check_type_safety(code),
"安全漏洞": check_security(code),
"性能问题": check_performance(code),
"代码复杂度": check_complexity(code)
}
# 生成报告
report = generate_report(checks)
# AI 提供改进建议
suggestions = ai_suggest_improvements(code, checks)
return {
"report": report,
"suggestions": suggestions
}
安全性最佳实践
安全检查清单
def security_checklist(code: str):
"""安全检查清单"""
prompt = f"""
请检查以下代码的安全性:
```
{code}
```
重点检查:
1. 输入验证
- [ ] 所有用户输入都经过验证
- [ ] 使用白名单而非黑名单
- [ ] 长度限制
2. SQL 注入
- [ ] 使用参数化查询
- [ ] 避免动态 SQL 拼接
3. XSS 防护
- [ ] 输出编码
- [ ] Content Security Policy
4. 认证授权
- [ ] 密码加密存储
- [ ] 会话管理安全
- [ ] 权限检查
5. 敏感数据
- [ ] 不在日志中记录敏感信息
- [ ] 使用环境变量存储密钥
- [ ] 加密传输
6. 错误处理
- [ ] 不泄露系统信息
- [ ] 统一错误响应格式
对于每个检查项:
- ✅ 通过
- ⚠️ 需要改进
- ❌ 存在问题
并给出具体的改进建议。
"""
return call_ai(prompt)
常见安全问题及修复
问题 1:SQL 注入
# ❌ 不安全
def get_user(username):
query = f"SELECT * FROM users WHERE username = '{username}'"
return db.execute(query)
# ✅ 安全
def get_user(username):
query = "SELECT * FROM users WHERE username = ?"
return db.execute(query, (username,))
问题 2:密码存储
# ❌ 不安全
def save_password(password):
user.password = password # 明文存储
# ✅ 安全
import bcrypt
def save_password(password):
salt = bcrypt.gensalt()
hashed = bcrypt.hashpw(password.encode(), salt)
user.password = hashed
问题 3:敏感信息泄露
# ❌ 不安全
API_KEY = "sk-1234567890abcdef" # 硬编码在代码中
# ✅ 安全
import os
API_KEY = os.environ.get("API_KEY") # 从环境变量读取
👥 团队协作
团队使用规范
提示词库管理
团队共享的提示词库:
project/
├── .prompts/
│ ├── python/
│ │ ├── api-endpoint.md
│ │ ├── data-model.md
│ │ └── unit-test.md
│ ├── frontend/
│ │ ├── react-component.md
│ │ └── api-integration.md
│ └── devops/
│ ├── docker.md
│ └── ci-cd.md
└── README.md
示例提示词模板 (api-endpoint.md):
# API 端点开发模板
## 提示词
创建一个 RESTful API 端点:
【功能】
{功能描述}
【路由】
- 方法:{GET/POST/PUT/DELETE}
- 路径:{/api/v1/...}
【请求】
- Headers:{...}
- Body:{...}
【响应】
- 成功:{200, 数据格式}
- 失败:{错误码, 错误格式}
【验证】
- 输入验证规则
- 权限验证
【错误处理】
- 异常类型及处理方式
【文档】
- 生成 OpenAPI/Swagger 文档
## 使用示例
[粘贴一个具体示例]
代码风格统一
# .ai-config.yaml
# AI 生成代码的风格配置
code_style:
language: python
version: "3.10+"
formatting:
line_length: 88
quotes: double
indent: 4
naming:
function: snake_case
class: PascalCase
constant: UPPER_CASE
documentation:
style: google # Google, NumPy, or reStructuredText
include_examples: true
include_types: true
imports:
order: [stdlib, third_party, local]
format: black
type_hints:
enabled: true
strict: false
error_handling:
prefer_specific_exceptions: true
always_cleanup: true
testing:
framework: pytest
coverage_target: 80
include_edge_cases: true
# 使用方式
# 在提示词中引用:
# "请按照我们的代码风格配置生成代码(参考 .ai-config.yaml)"
Git Commit 规范
# 使用 AI 生成规范的 commit message
# 你的输入:
git diff | ai-commit
# AI 生成:
feat(auth): 添加用户注册API
- 实现用户注册端点
- 添加邮箱验证
- 实现密码加密存储
- 添加单元测试(覆盖率85%)
Breaking Changes: None
Closes: #123
知识库建设
项目知识库结构
项目知识库/
├── 01-架构设计/
│ ├── 系统架构.md
│ ├── 数据库设计.md
│ └── API设计.md
│
├── 02-开发规范/
│ ├── 代码风格指南.md
│ ├── Git工作流.md
│ └── 测试规范.md
│
├── 03-常见模式/
│ ├── 认证授权模式.md
│ ├── 错误处理模式.md
│ └── 数据验证模式.md
│
├── 04-问题解决/
│ ├── 常见问题FAQ.md
│ ├── 性能优化案例.md
│ └── Bug修复记录.md
│
└── 05-最佳实践/
├── 安全最佳实践.md
├── 性能最佳实践.md
└── 可维护性最佳实践.md
使用 AI 维护知识库
async def update_knowledge_base(code_changes, issue_resolution):
"""自动更新知识库"""
# 1. 分析代码变更
patterns = await ai_analyze_patterns(code_changes)
# 2. 提取最佳实践
if is_good_practice(patterns):
await add_to_knowledge_base(
category="最佳实践",
content=patterns
)
# 3. 记录问题解决方案
if issue_resolution:
await add_to_knowledge_base(
category="问题解决",
content={
"problem": issue_resolution.problem,
"solution": issue_resolution.solution,
"code": issue_resolution.code
}
)
# 4. 生成文档
doc = await ai_generate_documentation(patterns)
await save_documentation(doc)
💡 最佳实践总结
核心原则
1. 人机协同
└─ AI 生成,人工审查
2. 持续迭代
└─ 不断优化提示词和工作流
3. 质量优先
└─ 代码质量不能妥协
4. 安全第一
└─ 始终考虑安全性
5. 团队协作
└─ 统一规范,共享知识
常见陷阱
❌ 盲目信任 AI 生成的代码
✅ 始终审查和测试
❌ 提示词过于简单
✅ 提供充分的上下文和约束
❌ 忽视安全性
✅ 重点关注安全问题
❌ 不写测试
✅ AI 可以帮助生成测试
❌ 缺乏文档
✅ 利用 AI 生成文档
🎯 下一步
掌握了最佳实践后,继续学习:
- 📖 07 - 性能优化技巧 - 提升效率和降低成本
- 📖 08 - 实战案例集 - 实践项目
- 📖 09 - 常见问题与故障排除 - 解决具体问题