文思AI产品笔记
首页
最新文章
AI编程
AI架构
关于我
  • AI生态圈
  • AI大模型
  • 多维表格
  • AI创业笔记
  • AI落地案例
  • 个人产品推介
  • 问题集
  • 简体中文
  • English
首页
最新文章
AI编程
AI架构
关于我
  • AI生态圈
  • AI大模型
  • 多维表格
  • AI创业笔记
  • AI落地案例
  • 个人产品推介
  • 问题集
  • 简体中文
  • English
  • OpenAI Codex 教程

    • OpenAI Codex 从入门到精通完整教程
    • Codex 快速入门指南
    • Codex 核心特点详解
    • Codex 版本演进历史
    • Codex 架构设计详解
    • Codex 高级功能与集成
    • Codex 最佳实践
    • Codex 性能优化技巧
    • Codex 实战案例集
    • Codex 常见问题与故障排除

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]
[粘贴现有代码]

【问题描述】

  • 性能瓶颈:[具体问题]
  • 可读性问题:[具体问题]
  • 维护性问题:[具体问题]

【优化目标】

  1. 主要目标:[性能/可读性/可维护性]
  2. 次要目标:[...]

【约束条件】

  • 保持功能不变
  • 兼容现有接口
  • 不引入新的依赖(如适用)

【期望输出】

  1. 优化后的代码
  2. 优化说明
  3. 性能对比(如适用)

**实际示例**:

【当前代码】

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

【问题描述】

  • 性能问题:处理大量用户时很慢
  • 可读性问题:逻辑混在一起
  • 没有类型注解和错误处理

【优化目标】

  1. 主要:提升性能(处理10万用户)
  2. 次要:提高可读性,添加错误处理

【约束条件】

  • 保持函数签名
  • Python 3.8+
  • 不引入外部依赖

【期望输出】

  1. 优化后的代码(使用列表推导式等)
  2. 性能提升说明
  3. 添加类型注解和错误处理

#### 模板 3:Bug 修复

【错误现象】 描述出现的错误或异常行为

【错误代码】

[粘贴有问题的代码]

【错误信息】

[粘贴完整的错误堆栈]

【预期行为】 描述正确的行为应该是什么

【环境信息】

  • 语言版本:[...]
  • 依赖版本:[...]
  • 操作系统:[...]

【已尝试的方案】

  1. [方案1] - 结果:[...]
  2. [方案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)

不好的提示: "优化这个算法"

好的提示(包含思维链): "请分析这个算法:

  1. 首先识别算法的时间复杂度
  2. 找出主要的性能瓶颈
  3. 提出3种优化方案
  4. 比较各方案的优缺点
  5. 选择最佳方案并实现
  6. 分析优化后的复杂度"

---

## 🚀 工作流设计

### 日常编码工作流

#### 流程图

┌──────────────────────────────────────┐ │ 日常编码工作流 │ ├──────────────────────────────────────┤ │ │ │ 1. 📝 需求分析 │ │ └─ 明确要实现的功能 │ │ │ │ 2. 🤔 方案设计 │ │ └─ 与 AI 讨论技术方案 │ │ │ │ 3. ✍️ 代码生成 │ │ ├─ 让 AI 生成框架代码 │ │ └─ 人工审查和调整 │ │ │ │ 4. 🔍 代码审查 │ │ ├─ AI 审查代码质量 │ │ └─ 人工审查业务逻辑 │ │ │ │ 5. 🧪 测试 │ │ ├─ AI 生成测试用例 │ │ └─ 运行测试 │ │ │ │ 6. 📚 文档 │ │ └─ AI 生成文档和注释 │ │ │ │ 7. 🚀 提交 │ │ └─ Git commit & push │ │ │ └──────────────────────────────────────┘


#### 实际操作示例

**场景**:开发一个用户注册API

**Step 1:需求分析**

你的输入: "我需要创建一个用户注册API,需要考虑哪些方面?"

AI 输出:

  1. 数据验证(邮箱、密码强度)
  2. 密码加密存储
  3. 邮箱唯一性检查
  4. 发送验证邮件
  5. 错误处理
  6. 速率限制
  7. 日志记录

**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 - 常见问题与故障排除 - 解决具体问题

👉 下一章:07 - 性能优化技巧

最近更新: 2025/12/22 14:25
Contributors: wsyx
Prev
Codex 高级功能与集成
Next
Codex 性能优化技巧