Prompt工程05：代码上下文

代码上下文是让模型理解代码结构和逻辑的关键。好的代码上下文能让模型更准确地理解代码意图，输出更高质量的修改建议。

代码上下文的重要性

缺少上下文的问题

当模型没有足够的代码上下文时：

用户输入：

帮我修改这个方法，使其支持分页查询。

问题：

• 模型不知道这是什么项目
• 不知道使用什么框架
• 不知道数据库结构
• 不知道现有的分页实现方式

有上下文的效果

用户输入：

项目：Spring Boot 电商系统
文件：src/main/java/com/example/service/OrderService.java
方法：getOrders()
当前实现：查询所有订单，没有分页
需求：支持分页查询，使用 Pageable 参数

相关代码：
```java
@Service
public class OrderService {
    @Autowired
    private OrderRepository orderRepository;
    
    public List<Order> getOrders() {
        return orderRepository.findAll();
    }
}

其他模块的分页实现参考：

public Page<Product> getProducts(Pageable pageable) {
    return productRepository.findAll(pageable);
}

效果：模型可以准确理解项目结构、现有模式，输出高质量的修改建议。

代码上下文的组成

核心要素

要素	内容	作用
仓库结构	目录树、模块划分	理解项目整体架构
关键文件	核心类、配置文件	理解关键逻辑
接口契约	API 定义、数据结构	理解接口规范
变更范围	需要修改的文件和方法	明确修改目标
代码风格	命名规范、设计模式	保持一致性

上下文层次

层次1：项目级别
├── 技术栈（Java、Spring Boot、MySQL）
├── 项目结构（目录树）
└── 核心配置（application.yml）

层次2：模块级别
├── 模块职责（用户模块、订单模块）
├── 关键类和接口
└── 依赖关系

层次3：代码级别
├── 当前代码
├── 相关代码
└── 测试代码

如何提供代码上下文

仓库结构

项目：电商系统
技术栈：Java 21 + Spring Boot 3.2 + MySQL

仓库结构：
├── src/main/java/com/example
│   ├── controller/     # REST API 控制层
│   ├── service/        # 业务逻辑层
│   ├── repository/     # 数据访问层
│   ├── entity/         # 数据库实体
│   ├── dto/            # 数据传输对象
│   └── config/         # 配置类
├── src/main/resources
│   ├── application.yml # 应用配置
│   └── schema.sql      # 数据库初始化
└── pom.xml             # Maven 依赖

关键文件

核心文件：
1. controller/OrderController.java - 订单 API 控制器
2. service/OrderService.java - 订单业务逻辑
3. repository/OrderRepository.java - 订单数据访问
4. entity/Order.java - 订单实体
5. dto/OrderDTO.java - 订单数据传输对象
6. config/WebConfig.java - Web 配置

接口契约

订单 API 接口：
POST /api/orders - 创建订单
GET /api/orders - 查询订单列表
GET /api/orders/{id} - 查询订单详情
PUT /api/orders/{id} - 更新订单
DELETE /api/orders/{id} - 删除订单

请求/响应格式：
请求：{"userId": 1, "items": [...], "totalAmount": 100.0}
响应：{"id": 1, "userId": 1, "status": "PENDING", "createdAt": "2024-01-15T10:00:00"}

变更范围

变更任务：为订单列表接口添加分页功能

需要修改的文件：
1. OrderController.java - 添加分页参数
2. OrderService.java - 修改查询方法
3. OrderRepository.java - 添加分页查询方法
4. OrderDTO.java - 添加分页响应结构

不需要修改的文件：
- entity/Order.java（数据结构不变）
- config/WebConfig.java（无相关配置）

代码上下文的格式

结构化上下文

[项目信息]
名称：电商系统
技术栈：Java 21 + Spring Boot 3.2 + MySQL

[仓库结构]
├── controller/
├── service/
├── repository/
├── entity/
├── dto/
└── config/

[关键文件]
- OrderController.java - 订单 API 控制器
- OrderService.java - 订单业务逻辑

[当前代码]
文件：OrderService.java
```java
@Service
public class OrderService {
    @Autowired
    private OrderRepository orderRepository;
    
    public List<Order> getOrders() {
        return orderRepository.findAll();
    }
}

[相关代码] 文件：ProductService.java（参考实现）

public Page<Product> getProducts(Pageable pageable) {
    return productRepository.findAll(pageable);
}

[需求] 为 getOrders() 方法添加分页支持，返回 Page 类型

### 上下文组织原则

| 原则 | 说明 | 示例 |
|------|------|------|
| 分层组织 | 按项目→模块→代码的顺序 | 先给仓库结构，再给具体代码 |
| 精简内容 | 只提供必要信息 | 不要粘贴整个文件 |
| 标注重点 | 对关键部分进行标注 | 使用注释或说明 |
| 提供参考 | 提供相似实现作为参考 | 分页实现参考 |

## 代码上下文的常见问题

### 问题1：上下文过多

**表现**：粘贴了大量无关代码，占用 Token

**解决方案**：
- 只粘贴相关部分
- 使用文件路径代替完整代码
- 提供代码摘要

### 问题2：上下文过少

**表现**：模型无法理解代码意图

**解决方案**：
- 添加项目背景信息
- 提供相关代码作为参考
- 说明代码的业务含义

### 问题3：上下文过时

**表现**：提供的代码已经过时

**解决方案**：
- 使用最新代码
- 注明代码版本
- 检查代码是否有变更

### 问题4：上下文不一致

**表现**：不同文件的代码风格不一致

**解决方案**：
- 统一代码风格
- 提供代码规范文档
- 说明特殊约定

## 代码上下文的工具支持

### IDE 集成工具

| 工具 | 功能 | 适用场景 |
|------|------|---------|
| Cursor | 直接读取当前文件和相关文件 | 日常开发 |
| GitHub Copilot | 根据代码上下文补全 | 代码编写 |
| Claude Code | 仓库级代码理解 | 大型项目 |

### 上下文提取工具

| 工具 | 功能 | 适用场景 |
|------|------|---------|
| tree | 生成目录树 | 了解项目结构 |
| grep | 搜索代码 | 查找特定代码 |
| ctags | 生成代码索引 | 快速定位 |
| IDE 搜索 | 项目内搜索 | 日常开发 |

## 代码上下文的最佳实践

### 日常开发中的上下文

角色：你是我的编程助手 目标：帮我修改代码

[上下文] 项目：电商系统 文件：OrderService.java 当前方法：getOrders() 需求：添加分页支持

[参考] ProductService.java 中的分页实现

[代码] 当前代码片段

### 代码审查中的上下文

角色：你是代码审查员 目标：审查这段代码的安全性和性能

[上下文] 项目：金融系统 文件：TransactionService.java 变更内容：新增转账方法

[业务背景] 这是核心转账逻辑，涉及资金安全

[代码] 待审查的代码片段

### 重构中的上下文

角色：你是架构师 目标：重构这个模块

[上下文] 项目：遗留系统 模块：订单模块 问题：代码耦合度高，难以维护

[约束] 不能修改 API 接口，需要保持向后兼容

[代码] 当前模块代码

## 项目判断清单

- 模型不理解代码结构 → 提供仓库结构和模块划分
- 模型不知道使用什么框架 → 提供技术栈信息
- 模型输出不符合代码风格 → 提供代码规范
- 需要修改多个文件 → 明确变更范围
- 需要参考现有实现 → 提供相关代码
- Token 预算有限 → 精简上下文，只提供关键部分
- 需要长期协作 → 建立项目上下文知识库
- 上下文效果不好 → 检查上下文完整性和准确性