错误定位 Prompt 实战：从异常堆栈到根因排查指南

2.3 错误定位 Prompt 的核心目标

一个高质量的错误定位 Prompt，需实现以下 3 个核心目标，确保模型输出具备实用性、精准性、可操作性：

1. 信息提取：从混乱的堆栈日志中，自动提取异常类型、错误位置、关键调用链路；
2. 根因推测：结合代码上下文，推测 2-3 个最可能的错误根因；
3. 行动指南：给出 step-by-step 的排查步骤，甚至生成调试代码片段。

三、错误定位 Prompt 的设计框架：从基础到进阶

错误定位 Prompt 的设计需遵循'信息引导 + 约束输出 + 场景补充'的逻辑，分为'基础模板'和'进阶模板'两类。

3.1 基础模板：面向新手，覆盖单一语言/单体应用

基础模板适用于单体应用、单一语言、无复杂上下文的错误场景，核心是'降低输入门槛'。

基础模板结构（通用版）

# 角色与任务
你是一位资深软件开发调试助手，擅长 [指定语言，如 Python/Java/JavaScript] 的错误定位。请基于我提供的异常堆栈日志，完成以下任务：

# 输入信息
异常堆栈日志：
[此处粘贴完整的异常堆栈日志]

# 输出要求（严格按以下结构输出，不要遗漏）
1. 异常核心信息提取：
   - 异常类型：[如 IndexError/NullPointerException]
   - 错误消息：[复制堆栈中的错误描述]
   - 错误位置：文件路径：[如 user_manage.py]，行号：[如 25]
   - 关键调用链路（仅保留业务代码）：[按'文件行号→函数名'格式列出]
2. 可能的错误根因（列出 2-3 个最可能的原因，结合代码逻辑推测）：
   - 根因 1：...
   - 根因 2：...
   - 根因 3：...
3. 排查步骤（step-by-step，从简单到复杂）：
   Step 1：...
   Step 2：...
   Step 3：...
4. 调试代码片段（可选，若适用）：
   [生成可直接插入的调试代码]

基础模板实战案例（Python 索引越界错误）

开发者输入（堆栈日志）

Traceback (most recent call last):
  File "user_manage.py", line 25, in get_user_info
    return users[index]
  File "main.py", line 18, in <module>
    user = get_user_info(5)
IndexError: list index out of range

模型输出（基于基础模板）

1. 异常核心信息提取：
   • 异常类型：IndexError（列表索引越界）
   • 错误消息：list index out of range
   • 错误位置：文件路径：user_manage.py，行号：25
   • 关键调用链路：main.py 第 18 行→get_user_info → user_manage.py 第 25 行→return users[index]
2. 可能的错误根因：
   • 根因 1：传入的 index=5 超过列表 users 的实际长度（推测 users 列表长度≤4），导致索引越界。
   • 根因 2：函数 get_user_info 未对输入参数 index 进行合法性校验，直接使用参数访问列表。
   • 根因 3：列表 users 在初始化时未成功加载数据（如从数据库查询用户失败，返回空列表）。
3. 排查步骤：
   • Step 1：打开 user_manage.py 文件，定位第 25 行，查看 users 列表的定义位置，打印 len(users) 确认列表实际长度。
   • Step 2：跳转至 main.py 第 18 行，检查调用 get_user_info 时传入的 index=5 是否合理。
   • Step 3：在 get_user_info 函数开头添加调试日志，重新运行程序验证根因。
4. 调试代码片段：

# 优化后的 get_user_info 函数（添加参数校验与调试日志）
def get_user_info(index):
    # 调试日志：打印关键变量
    print(f"调试信息 - index: {index}, users 长度：{len(users)}, users: {users}")
    # 参数合法性校验
    if not isinstance(index, int):
        raise TypeError("index 必须为整数")
    if index < 0 or index >= len(users):
        raise ValueError(f"index 超出有效范围，当前 users 列表长度为{len(users)}，有效 index 范围：0~{len(users)-1}")
    return users[index]

3.2 进阶模板：面向资深开发者，覆盖跨服务/复杂场景

进阶模板适用于微服务、分布式应用、多语言混合架构的复杂错误场景，核心是'补充上下文信息'。

进阶模板结构（微服务版）

# 角色与任务
你是一位微服务架构调试专家，擅长分析跨服务调用中的错误根因，熟悉 [指定技术栈，如 Spring Cloud/Dubbo + MySQL + Redis]。请基于我提供的'异常堆栈 + 调用链路 + 上下文信息'，完成深度错误定位。

# 输入信息（请开发者按以下格式补充，缺一不可）
1. 异常堆栈日志（当前服务的完整堆栈）：
[此处粘贴当前服务的异常堆栈]
2. 跨服务调用链路（如 APM 工具记录的链路）：
[如：用户服务→订单服务→/api/order/create]
3. 上下文补充：
   - 输入数据（当前接口的请求参数，脱敏处理）：
   - 相关配置（如数据库连接、Redis 地址）：
   - 异常发生时间与频率：

# 输出要求（严格按以下结构，需包含跨服务排查点）
1. 异常核心信息提取（含跨服务关联）：
   - 异常类型与错误消息：
   - 错误位置（当前服务）：
   - 跨服务调用链路梳理：
2. 多维度根因分析（分'代码层''配置层''依赖层'）：
   - 代码层根因：
   - 配置层根因：
   - 依赖层根因：
3. 跨服务排查步骤（按'当前服务→上游服务→依赖服务'顺序）：
   Step 1：排查当前服务
   Step 2：排查上游服务
   Step 3：排查依赖服务
4. 解决方案与优化建议（含跨服务协同）：
   - 短期修复：
   - 长期优化：

进阶模板实战案例（微服务订单创建错误）

开发者输入（完整上下文）

1. 异常堆栈日志（order-service）：

org.springframework.dao.DataIntegrityViolationException: ### Error updating database. Cause: com.mysql.cj.jdbc.exceptions.MysqlDataTruncation: Data truncation: Check constraint 'order_quantity_check' violated for table 'order'
...
at com.order.service.impl.OrderServiceImpl.createOrder(OrderServiceImpl.java:65)
...
at com.order.controller.OrderController.createOrder(OrderController.java:48)

2. 跨服务调用链路：user-service → order-service → /api/order/create
3. 上下文补充：
   • 输入数据：{"userId": "12345", "productId": "P001", "quantity": -2}
   • 相关配置：MySQL 地址：jdbc:mysql://192.168.1.100:3306/order_db；quantity 字段约束：CHECK (quantity > 0)

模型输出（基于进阶模板）

1. 异常核心信息提取：
   • 异常类型：DataIntegrityViolationException，根因：MySQL 的 order_quantity_check 约束被违反（quantity 字段需>0）。
   • 错误位置：OrderServiceImpl.java 第 65 行，OrderController.java 第 48 行。
   • 跨服务调用链路：user-service→order-service（传递参数 quantity=-2）→ MySQL 执行 INSERT 语句时触发 CHECK 约束。
2. 多维度根因分析：
   • 代码层根因：order-service 的 Controller 和 Service 均未对 quantity 参数进行合法性校验，直接将负数参数传递至 MyBatis。
   • 配置层根因：MySQL 虽设置了 CHECK 约束，但未在应用层提前拦截，导致异常需通过数据库层抛出。
   • 依赖层根因：前端页面可能未添加 quantity 的输入校验，或校验被绕过。
3. 跨服务排查步骤：
   • Step 1：排查当前服务（order-service）：检查 OrderController.java 第 48 行，确认是否使用 JSR-380 校验注解（如@Min(1)）。
   • Step 2：排查上游服务（user-service）：找到 Feign 客户端，查看是否有参数校验逻辑。
   • Step 3：排查依赖服务（MySQL）：登录数据库，执行 SELECT * FROM order WHERE quantity <= 0; 确认是否存在历史非法数据。
4. 解决方案与优化建议：
   • 短期修复：在 order-service 的 createOrder 方法的 quantity 参数上添加 @Min(value = 1)；在 user-service 的 Feign 调用前添加参数校验。
   • 长期优化：引入公共校验组件，统一校验标准；接入 APM 工具设置异常告警规则。

四、不同语言/场景的错误定位 Prompt 适配技巧

不同编程语言的异常堆栈格式、错误类型命名存在差异，需根据具体场景调整 Prompt 的'语言特性'与'输出侧重点'。

4.1 多语言适配：Java、Python、JavaScript 差异调整

1. Java 场景：突出'异常链'与'框架层级过滤'

Java 堆栈常包含大量框架代码（如 Spring、MyBatis），Prompt 需明确'过滤框架无关调用'，同时关注'异常链'。

Java 专属 Prompt 片段：

# 语言特性适配
- 请识别异常链中的'根异常'（如被 cause 包裹的 MysqlDataTruncation），优先基于根异常分析根因；
- 过滤框架底层代码调用（如 org.springframework.*、org.mybatis.*），仅保留业务代码；
- 若涉及 Spring Boot 框架，请额外分析是否为'配置错误'或'依赖冲突'。

2. Python 场景：关注'模块导入'与'第三方库错误'

Python 错误常涉及模块导入、第三方库使用，Prompt 需引导模型分析'依赖安装'与'库版本兼容性'。

Python 专属 Prompt 片段：

# 语言特性适配
- 若异常类型为 ModuleNotFoundError，请优先分析'是否已安装该模块'及'Python 环境是否正确'；
- 若涉及第三方库（如 pandas、requests），请推测是否为'库版本不兼容'，并建议查看库的官方文档确认用法；
- 若为装饰器、生成器相关错误，请结合 Python 语法特性分析。

3. JavaScript（前端/Node.js）场景：区分'语法错误'与'运行时错误'

JS 错误分为语法错误和运行时错误，前端场景还需关注'DOM 操作''异步请求'。

JavaScript 专属 Prompt 片段：

# 语言特性适配（区分前端/Node.js）
- 若为前端场景：
  1. 若涉及 DOM 操作，请分析'DOM 元素是否存在'；
  2. 若为异步请求错误，请分析'请求 URL 是否正确''跨域配置是否缺失'。
- 若为 Node.js 场景：
  1. 若涉及文件操作，请分析'文件路径是否正确'、'文件权限是否足够'；
  2. 若为 EventEmitter 相关错误，请建议添加 error 事件监听避免程序崩溃。

4.2 特殊场景适配：数据库错误、分布式链路错误

1. 数据库错误场景

数据库错误的根因常涉及'SQL 语法''字段约束''连接配置'，Prompt 需引导模型分析 SQL 语句与数据库配置的匹配性。

数据库错误专属 Prompt 片段：

# 数据库场景适配
- 若为 SQL 语法错误：请检查 SQL 语句的'关键字拼写'、'括号/引号配对'、'表名/字段名大小写'；
- 若为连接错误：请检查数据库'连接地址、端口、用户名、密码'是否正确，分析'数据库是否启动'、'网络是否可达'；
- 若为 NoSQL 数据库：请检查查询条件是否符合 MongoDB 语法，或集合是否存在。

2. 分布式链路错误场景

分布式错误的根因常涉及'服务间通信''分布式事务一致性'，Prompt 需引导模型分析'上游服务状态''网络链路'。

分布式链路专属 Prompt 片段：

# 分布式场景适配
- 请结合 APM 调用链路分析以下点：
  1. 上游服务是否正常返回（如 user-service 是否返回 200，是否存在超时）；
  2. 服务间通信协议是否存在问题（如 Dubbo 调用的序列化方式不兼容）；
  3. 分布式事务是否触发回滚。
- 若涉及消息队列：分析'消息是否成功发送'、'消费者是否正常消费'。

五、错误定位 Prompt 的输出优化：避免泛泛而谈，提升实用性

即使使用上述模板，模型仍可能输出'泛泛而谈'的建议。需通过'约束输出细节''添加负面清单''示例引导'三个技巧，提升输出的精准性与可操作性。

5.1 技巧 1：约束输出细节

在 Prompt 的输出要求中，明确'禁止模糊表述'，强制模型结合输入的堆栈信息，输出具体的文件路径、行号，甚至推测可能的代码片段。

反例（泛泛而谈）： '请检查 quantity 参数的校验逻辑，确保其为正数。'

正例（具体细节）： '请检查 order-service 的 OrderController.java 第 48 行，确认是否在 createOrder 方法的 quantity 参数上添加了@Min(1) 注解；若未添加，请补充该注解，并在全局异常处理器中捕获 MethodArgumentNotValidException。'

Prompt 约束语句：

# 输出细节约束
- 所有排查步骤必须'具体到文件路径、行号、方法名'，禁止使用'某个文件''某段代码'等模糊表述；
- 根因分析需结合输入的'异常堆栈 + 上下文信息'，禁止输出与当前场景无关的通用建议；
- 调试代码片段需可直接运行，并标注'需替换的变量'。

5.2 技巧 2：添加负面清单

提前在 Prompt 中列出'禁止输出的内容'，避免模型输出无用信息，聚焦错误定位本身。

负面清单示例：

# 输出负面清单（禁止包含以下内容）
1. 禁止讲解基础编程语言语法（如'Java 的 try-catch 语句用法'）；
2. 禁止输出与当前错误无关的通用开发规范（如'代码缩进应使用 4 个空格'）；
3. 禁止使用过于学术化的表述，需用通俗语言解释，并直接关联解决方案；
4. 禁止推荐未经验证的工具或框架。

5.3 技巧 3：示例引导

若模型对复杂场景的输出仍不理想，可在 Prompt 中添加'正确输出示例'，让模型参考示例的结构与细节程度。

示例引导片段（Java 空指针错误）：

# 正确输出示例参考
假设输入堆栈为：java.lang.NullPointerException: Cannot invoke "com.user.entity.User.getName()" because "user" is null at com.user.service.UserServiceImpl.getUserName(UserServiceImpl.java:32)

正确输出参考（根因分析部分）：
- 根因 1：UserServiceImpl.java 第 32 行调用 user.getName() 时，user 对象为 null，推测'获取 user 对象的逻辑存在漏洞'；
- 根因 2：UserController.java 第 20 行调用 UserServiceImpl.getUserName 时，传入的 user 对象为 null。

请参考上述示例的细节程度，分析当前问题的根因，确保每个根因都关联具体的文件、行号与代码逻辑。

六、章节总结与课后练习

6.1 章节总结

本章系统讲解了错误定位 Prompt 的设计与应用，核心要点可归纳为：

1. 基础认知：异常堆栈是错误定位的核心证据，需提取'异常类型、错误位置、调用链路'三大信息；
2. 模板设计：基础模板面向单体应用/新手，侧重'结构化输出'；进阶模板面向微服务/资深开发者，侧重'跨服务关联分析'；
3. 场景适配：根据语言（Java/Python/JS）、场景（数据库/分布式）调整 Prompt 的'语言特性'与'排查重点'；
4. 输出优化：通过'约束细节、负面清单、示例引导'，避免模型输出泛泛而谈，提升建议的可操作性。

掌握错误定位 Prompt 的设计技巧，能让开发者将大语言模型转化为'专属调试助手'，大幅减少排查错误的时间。

6.2 课后练习

练习 1：Python 字典键不存在错误（基础场景）

任务：基于以下异常堆栈，使用'基础模板'设计 Prompt，并生成模型输出。

输入堆栈日志：

Traceback (most recent call last):
  File "product_manage.py", line 38, in get_product_price
    return product["price"]  # 尝试获取字典中不存在的"price"键
  File "main.py", line 22, in <module>
    price = get_product_price({"id": "P001", "name": "手机"})
KeyError: 'price'

练习 2：Java 微服务数据库连接错误（进阶场景）

任务：基于以下上下文信息，使用'进阶模板'设计 Prompt。

输入信息：

1. 异常堆栈日志（product-service）：

org.springframework.jdbc.CannotGetJdbcConnectionException: Failed to obtain JDBC Connection; nested exception is com.mysql.cj.jdbc.exceptions.CommunicationsException: Communications link failure
...
at com.product.service.impl.ProductServiceImpl.getProductById(ProductServiceImpl.java:42)

2. 跨服务调用链路：api-gateway → product-service → /api/product/getById
3. 上下文补充：
   • 输入数据：请求 URL：http://localhost:8080/api/product/getById?id=P001
   • 相关配置：product-service 的 application.yml 中数据库配置：spring.datasource.url: jdbc:mysql://192.168.1.200:3306/product_db?useSSL=false
   • 异常发生情况：所有调用 product-service 的请求均触发该错误，重启服务后仍无法解决；其他服务（如 user-service）可正常连接 MySQL（地址：192.168.1.100:3306）。

练习 3：前端 JavaScript 异步请求错误（场景适配）

任务：基于以下前端错误信息，设计'JavaScript 前端专属 Prompt'。

输入信息：

1. 浏览器控制台错误：

Uncaught (in promise) AxiosError: Request failed with status code 404 at settle (axios.min.js:1:14975) at getProductDetail (productDetail.js:15)

2. 上下文补充：
   • 操作步骤：用户在 productDetail.html 页面点击'查看商品详情'按钮，触发 onclick 事件调用 getProductDetail 函数；
   • 后端服务信息：后端商品服务的正确接口地址为 /api/product/getDetail（非 /api/product/detail），服务已启动，端口 8080。

相关代码（productDetail.js 第 15 行）：

async function getProductDetail(){
    const productId = document.getElementById("productId").value;
    const response = await axios.get("/api/product/detail", {
        params: { id: productId }
    }); // 第 15 行
    console.log(response.data);
}

6.3 练习参考答案（思路点拨）

练习 1 参考答案思路

1. 异常核心信息提取：
   • 异常类型：KeyError（字典键不存在）；
   • 错误位置：product_manage.py 第 38 行，get_product_price 函数；
   • 关键调用链路：main.py 第 22 行→get_product_price → product_manage.py 第 38 行→return product["price"]。
2. 根因分析：
   • 根因 1：传入的 product 字典仅包含"id"和"name"键，无"price"键；
   • 根因 2：get_product_price 函数未判断"price"键是否存在，直接访问键。
3. 排查步骤：
   • Step 1：检查 main.py 第 22 行，确认传入的 product 字典是否应包含"price"键；
   • Step 2：在 product_manage.py 第 38 行前添加键存在性判断。
4. 调试代码：

def get_product_price(product):
    # 检查键是否存在
    if not isinstance(product, dict):
        raise TypeError("product 必须为字典类型")
    if "price" not in product:
        raise KeyError(f"product 字典缺少'price'键，当前键列表：{list(product.keys())}")
    return product["price"]

练习 2 参考答案思路

1. 异常核心信息提取：
   • 异常类型：CannotGetJdbcConnectionException，根因：CommunicationsException（通信链路失败）；
   • 跨服务链路：api-gateway→product-service:/api/product/getById→ product-service 连接 MySQL（192.168.1.200:3306）失败。
2. 多维度根因分析：
   • 配置层根因：product-service 的 MySQL 地址配置错误（192.168.1.200:3306），而其他服务使用 192.168.1.100:3306 可正常连接，推测地址写错；
   • 依赖层根因：192.168.1.200 的 MySQL 未启动、端口被占用，或网络防火墙禁止 product-service 访问该地址。
3. 排查步骤：
   • Step 1：检查 product-service 的 application.yml，确认 MySQL 地址是否应为 192.168.1.100:3306；
   • Step 2：在 product-service 服务器上执行 ping 和 telnet 测试网络连通性；
   • Step 3：登录 192.168.1.200 服务器，确认 MySQL 是否启动。
4. 解决方案：
   • 修改 application.yml 的 MySQL 地址为 jdbc:mysql://192.168.1.100:3306/product_db?useSSL=false，重启 product-service。

练习 3 参考答案思路

1. 异常核心信息提取：
   • 异常类型：AxiosError（404 Not Found）；
   • 错误位置：productDetail.js 第 15 行，getProductDetail 函数；
   • 触发链路：productDetail.html 第 28 行→ getProductDetail → 调用 Axios 请求 /api/product/detail→ 404 错误。
2. 根因分析：
   • 根因 1：Axios 请求的接口地址错误（/api/product/detail），后端正确地址为 /api/product/getDetail；
   • 根因 2：未处理 Axios 请求的 Promise 异常，导致'Uncaught (in promise)'错误。
3. 排查步骤：
   • Step 1：打开浏览器'网络'面板，查看 GET 请求的'请求 URL'，对比后端正确地址；
   • Step 2：修改 productDetail.js 第 15 行的接口地址为 /api/product/getDetail；
   • Step 3：在 getProductDetail 函数中添加 try-catch 捕获 Promise 异常。
4. 调试代码：

async function getProductDetail(){
    try{
        const productId = document.getElementById("productId").value;
        // 1. 验证 productId 是否为空
        if(!productId){
            alert("请输入商品 ID");
            return;
        }
        // 2. 修正接口地址为正确的/getDetail
        const response = await axios.get("/api/product/getDetail", {
            params: { id: productId }
        });
        console.log(response.data);
    }catch(error){
        // 3. 捕获并处理异常
        if(error.response){
            alert(`请求错误：${error.response.status} - ${error.response.statusText}`);
        }else if(error.request){
            alert("网络错误，无法连接服务器");
        }else{
            alert(`请求失败：${error.message}`);
        }
    }
}