AI 提示词重构建议：提升代码可读性的实战指南

// 正例：拆分 3 个单一职责函数，逻辑分层清晰
public class DataProcessor {
    // 仅负责读取文件
    public List<Double> readDataFromFile(String filePath) throws IOException {
        List<Double> data = new ArrayList<>();
        try (BufferedReader br = new BufferedReader(new FileReader(filePath))) {
            String line;
            while ((line = br.readLine()) != null) {
                data.add(Double.parseDouble(line));
            }
        }
        return data;
    }
    // 仅负责计算平均值
    public double calculateAverage(List<Double> data) {
        double sum = 0;
        for (double num : data) {
            sum += num;
        }
        return sum / data.size();
    }
    // 仅负责输出结果
    public void printResult(double average) {
        System.out.println("数据平均值：" + average);
    }
}

逻辑简化

1. 避免多层嵌套（≤3 层）
2. 减少冗余判断（如用三元运算符/枚举替代复杂 if-else）
3. 消除死代码/未使用变量

// 反例：4 层嵌套 + 冗余判断
function getDiscount(price, userType, isNewUser, hasCoupon) {
    let discount = 0;
    if (userType === "VIP") {
        if (isNewUser) {
            discount = 0.8;
            if (hasCoupon) {
                discount = 0.7;
            }
        } else {
            if (hasCoupon) {
                discount = 0.85;
            } else {
                discount = 0.9;
            }
        }
    }
    return price * discount;
}

// 正例：用对象映射替代嵌套，逻辑扁平化
function getDiscount(price, userType, isNewUser, hasCoupon) {
    // 定义折扣规则映射表，清晰可见
    const discountRules = {
        VIP: { new: { coupon: 0.7, noCoupon: 0.8 }, old: { coupon: 0.85, noCoupon: 0.9 } },
        normal: { new: { coupon: 0.95, noCoupon: 1.0 }, old: { coupon: 0.98, noCoupon: 1.0 } }
    };
    // 简化判断逻辑
    const userTier = isNewUser ? "new" : "old";
    const couponStatus = hasCoupon ? "coupon" : "noCoupon";
    const discount = discountRules[userType]?.[userTier]?.[couponStatus] || 1.0;
    return price * discount;
}

注释完整性

1. 类/函数需有文档注释（说明功能、参数、返回值）
2. 复杂逻辑处需有单行注释（解释'为什么'而非'是什么'）
3. 避免过时注释（注释与代码逻辑一致）

# 反例：无文档注释，复杂逻辑无说明
def format_date(date_str):
    parts = date_str.split("-")
    if len(parts) == 3:
        return f"{parts[2]}/{parts[1]}/{parts[0]}"
    else:
        return "Invalid"

# 正例：完整文档注释 + 逻辑说明
def format_date(date_str: str) -> str:
    """将 ISO 日期格式（YYYY-MM-DD）转换为日/月/年格式（DD/MM/YYYY）
    参数：
        date_str: str - 输入的日期字符串，需符合 ISO 格式（如"2024-05-20"）
    返回：
        str - 转换后的日期字符串，若格式无效则返回"Invalid Date"
    说明：
        1. 先按"-"分割字符串，判断是否为 3 个部分（年/月/日）
        2. 若格式正确，重组为 DD/MM/YYYY；否则返回无效提示
    """
    parts = date_str.split("-")
    # 验证 ISO 格式有效性（长度为 3 且各部分为数字）
    if len(parts) == 3 and all(part.isdigit() for part in parts):
        return f"{parts[2]}/{parts[1]}/{parts[0]}"
    else:
        return "Invalid Date"

代码复用

1. 提取重复逻辑为公共函数/工具类
2. 避免硬编码（用常量/配置替代魔法值）
3. 遵循 DRY 原则（Don't Repeat Yourself）

// 反例：重复计算逻辑 + 硬编码魔法值
public class OrderCalculator {
    // 计算 A 商品总价：重复逻辑
    public double calculateProductA(double quantity) {
        return quantity * 99.9; // 硬编码单价
    }
    // 计算 B 商品总价：重复逻辑
    public double calculateProductB(double quantity) {
        return quantity * 199.9; // 硬编码单价
    }
}

// 正例：提取公共方法 + 定义常量
public class OrderCalculator {
    // 定义商品单价常量，集中管理
    private static final double PRODUCT_A_PRICE = 99.9;
    private static final double PRODUCT_B_PRICE = 199.9;
    // 公共计算方法，复用逻辑
    private double calculateProductTotal(double quantity, double price) {
        return quantity * price;
    }
    // 调用公共方法，避免重复
    public double calculateProductA(double quantity) {
        return calculateProductTotal(quantity, PRODUCT_A_PRICE);
    }
    public double calculateProductB(double quantity) {
        return calculateProductTotal(quantity, PRODUCT_B_PRICE);
    }
}

重构建议 Prompt 的设计框架：从基础到进阶

重构建议 Prompt 的核心目标是'让 LLM 精准理解代码问题，并生成可执行的重构方案'。其设计需遵循'明确指令 + 上下文信息 + 约束条件'的结构，不同复杂度的场景对应不同的 Prompt 模板。以下分基础版、进阶版、专家版三个层级，拆解 Prompt 的设计逻辑，并结合案例说明适用场景。

（一）基础版 Prompt：适用于简单代码片段重构

核心场景：新手开发人员处理独立函数/代码块（如单个 Python 函数、Java 方法），需解决基础可读性问题（命名、简单嵌套、注释缺失）。 设计逻辑：以'原始代码 + 核心需求'为核心，减少额外约束，让模型聚焦基础优化。 模板结构：

指令：作为一名资深软件开发工程师，请帮我重构以下代码，提升其可读性。
原始代码：[粘贴待重构的代码片段]
重构要求：
1. 优化命名（变量名、函数名需体现功能，避免歧义）；
2. 简化逻辑（消除冗余判断、减少嵌套）；
3. 补充必要注释（函数文档注释 + 复杂逻辑单行注释）；
4. 输出格式：先提供重构后的完整代码，再分点说明重构点及原因。

实战案例：重构 Python 数据处理函数

1. 待重构代码（新手编写，存在命名模糊、无注释、冗余逻辑问题）：

def f1(d, k):
    res = []
    for i in d:
        if i == k:
            v = d[i]
            if v > 10:
                res.append(v)
    return res

2. 基础版 Prompt 完整输入：

指令：作为一名资深 Python 开发工程师，请帮我重构以下代码，提升其可读性。
原始代码：
def f1(d, k):
    res = []
    for i in d:
        if i == k:
            v = d[i]
            if v > 10:
                res.append(v)
    return res
重构要求：
1. 优化命名（变量名、函数名需体现功能，避免歧义，遵循 Python 蛇形命名法）；
2. 简化逻辑（消除冗余判断、减少嵌套，可使用列表推导式）；
3. 补充必要注释（函数需有文档注释，说明参数、返回值、功能；复杂逻辑处需单行注释）；
4. 输出格式：先提供重构后的完整代码，再分点说明重构点及原因。

3. 模型输出结果：

# 重构后的代码
def filter_dict_values_by_key(dict_data: dict, target_key: str) -> list:
    """根据指定键筛选字典中大于 10 的值，并返回结果列表
    参数：
        dict_data: dict - 输入的字典，键为字符串类型，值为数字类型
        target_key: str - 需要筛选的目标键
    返回：
        list - 符合条件的值组成的列表（仅包含 target_key 对应的值且该值>10）
    """
    # 使用列表推导式简化循环 + 判断逻辑，减少嵌套层级
    return [value for key, value in dict_data.items() if key == target_key and value > 10]

# 重构点及原因说明：
# 1. 函数名优化：将"f1"改为"filter_dict_values_by_key"，直接体现'按键筛选字典值'的核心功能，符合 Python 命名规范；
# 2. 参数名优化：将"d"改为"dict_data"（明确为字典数据），"k"改为"target_key"（明确为目标键），避免歧义；
# 3. 变量名优化：删除冗余变量"v"（直接用"value"替代），删除临时变量"res"（用列表推导式直接返回结果）；
# 4. 逻辑简化：将 2 层 for-if 嵌套改为 1 层列表推导式，代码行数从 8 行减少到 1 行，且逻辑更直观；
# 5. 注释补充：添加完整文档注释（说明功能、参数、返回值），为列表推导式添加单行注释，解释逻辑目的。

4. 效果验证：重构后的代码满足所有可读性维度——命名清晰、逻辑扁平化、注释完整，新手可直接理解功能，且可复用性提升（函数名明确，无需猜测用途）。

（二）进阶版 Prompt：适用于模块级重构与行业规范

核心场景：中高级开发人员处理多函数/类的模块重构（如一个 Python 工具类、Java 服务层模块），需符合行业特定规范（如 Google 代码规范、RESTful API 开发规范）或框架约束（如 Spring Boot、Django）。 设计逻辑：在基础版上增加'上下文信息'（如模块功能、使用框架、行业规范）和'进阶需求'（如依赖管理、性能优化、兼容性保障），让模型生成符合实际项目场景的方案。 模板结构：

指令：作为一名熟悉 [框架/行业] 的资深开发工程师，请帮我重构以下模块代码，需符合 [行业规范]，同时保障重构后功能一致性。
模块上下文：
1. 模块功能：[说明该模块的核心作用，如'用户订单数据处理模块，负责订单创建、价格计算、状态更新']；
2. 技术栈：[说明使用的框架/语言版本，如'Java 17 + Spring Boot 3.0，数据库为 MySQL 8.0']；
3. 依赖关系：[说明该模块与其他模块的关联，如'依赖用户模块（获取用户等级）、商品模块（获取商品单价）']；
重构要求：
1. 结构优化：按 [设计原则，如'单一职责原则'] 拆分类/函数，避免一个类承担过多功能；
2. 规范适配：符合 [具体规范，如'Google Java 代码规范''RESTful API 设计规范']；
3. 性能保障：避免 [性能问题，如'循环查询数据库''大对象频繁创建']；
4. 兼容性：重构后需兼容 [旧版本/调用方，如'兼容旧版订单查询接口（/v1/order/get）']；
5. 输出格式：
   a. 重构后的完整模块代码（按类/函数拆分，标注文件路径）；
   b. 重构方案说明（分'结构调整''规范适配''性能优化'三部分）；
   c. 风险提示（如'需注意的兼容性问题''测试重点'）。
原始代码：[按文件粘贴模块代码，如'OrderService.java''OrderUtil.java']

实战案例：重构 Java Spring Boot 订单服务模块

1. 模块上下文与待重构代码：
   • 模块功能：电商订单服务模块，负责订单创建、价格计算（含折扣）、订单状态更新；
   • 技术栈：Java 17 + Spring Boot 3.0，依赖 Spring Data JPA；
   • 待重构代码（OrderService.java，存在职责混乱、硬编码、无异常处理问题）：

@Service
public class OrderService {
    @Autowired
    private OrderRepository orderRepo;
    @Autowired
    private UserRepository userRepo;
    @Autowired
    private ProductRepository productRepo;

    // 1. 订单创建：同时处理数据校验、价格计算、数据库保存
    public Order createOrder(Long userId, List<Long> productIds, Integer couponId) {
        // 数据校验
        User user = userRepo.findById(userId).get();
        if (user == null) {
            System.out.println("用户不存在");
        }
        List<Product> products = new ArrayList<>();
        for (Long id : productIds) {
            products.add(productRepo.findById(id).get());
        }
        // 价格计算
        double total = 0;
        for (Product p : products) {
            total += p.getPrice();
        }
        // 折扣计算（硬编码）
        if (user.getLevel() == 1) {
            total *= 0.9;
        } else if (user.getLevel() == 2) {
            total *= 0.8;
        }
        if (couponId == 1001) {
            total -= 50;
        }
        // 订单保存
        Order order = new Order();
        order.setUserId(userId);
        order.setProductIds(productIds.toString());
        order.setTotalPrice(total);
        order.setStatus(0);
        return orderRepo.save(order);
    }

    // 2. 订单状态更新：无异常处理，状态值硬编码
    public void updateOrderStatus(Long orderId, Integer status) {
        Order order = orderRepo.findById(orderId).get();
        order.setStatus(status);
        orderRepo.save(order);
    }

    // 3. 辅助函数：计算商品总价（与 createOrder 中逻辑重复）
    public double calculateProductTotal(List<Product> products) {
        double total = 0;
        for (Product p : products) {
            total += p.getPrice();
        }
        return total;
    }
}

2. 进阶版 Prompt 完整输入：

指令：作为一名熟悉 Spring Boot 3.0 的电商领域资深开发工程师，请帮我重构以下订单服务模块代码，需符合 Google Java 代码规范和电商系统设计原则，同时保障重构后功能一致性。
模块上下文：
1. 模块功能：电商订单服务模块，负责订单创建、价格计算（含用户等级折扣、优惠券折扣）、订单状态更新；
2. 技术栈：Java 17 + Spring Boot 3.0，使用 Spring Data JPA 操作 MySQL 8.0 数据库，Lombok 简化 POJO 代码；
3. 依赖关系：依赖用户模块（UserRepository，获取用户等级）、商品模块（ProductRepository，获取商品信息）、优惠券模块（后续将接入，当前暂用 couponId 判断）；
重构要求：
1. 结构优化：按'单一职责原则'拆分 OrderService 中的功能，将价格计算、数据校验拆分到独立类/方法；
2. 规范适配：符合 Google Java 代码规范（如变量命名、注释格式、异常处理），使用 Lombok 注解（@Slf4j、@Data）简化代码；
3. 性能保障：避免循环查询数据库（当前无此问题，但需保持），消除硬编码（将折扣规则、订单状态值定义为常量）；
4. 兼容性：重构后 createOrder 方法的入参、返回值不变，兼容现有调用方（如订单 Controller）；
5. 输出格式：
   a. 重构后的完整模块代码（按类拆分，标注文件路径，如'com.ecommerce.order.service.OrderService.java'）；
   b. 重构方案说明（分'结构调整''规范适配''性能优化'三部分）；
   c. 风险提示（测试重点、后续可优化方向）。
原始代码：[粘贴上述 OrderService.java 代码]

3. 模型输出结果（核心部分）：

a. 重构后的代码文件（共 3 个类，拆分职责）

1. 订单状态/折扣常量类（OrderConstant.java）

package com.ecommerce.order.constant;

/**
 * 订单模块常量定义类，集中管理硬编码值，便于维护
 */
public class OrderConstant {
    // 订单状态：0-待支付，1-已支付，2-已发货，3-已完成，4-已取消
    public static final Integer ORDER_STATUS_PENDING = 0;
    public static final Integer ORDER_STATUS_PAID = 1;
    public static final Integer ORDER_STATUS_SHIPPED = 2;
    public static final Integer ORDER_STATUS_COMPLETED = 3;
    public static final Integer ORDER_STATUS_CANCELLED = 4;

    // 用户等级折扣：1-白银（9 折），2-黄金（8 折）
    public static final double USER_LEVEL_1_DISCOUNT = 0.9;
    public static final double USER_LEVEL_2_DISCOUNT = 0.8;

    // 优惠券面值：1001-50 元优惠券
    public static final Integer COUPON_ID_50 = 1001;
    public static final double COUPON_AMOUNT_50 = 50.0;
}

2. 价格计算工具类（OrderPriceCalculator.java）

package com.ecommerce.order.util;

import com.ecommerce.order.constant.OrderConstant;
import com.ecommerce.order.entity.Product;
import com.ecommerce.order.entity.User;
import org.springframework.stereotype.Component;
import java.util.List;

/**
 * 订单价格计算工具类，负责商品总价、折扣价的计算，遵循单一职责原则
 */
@Component
public class OrderPriceCalculator {
    /**
     * 计算商品原始总价（无折扣）
     * @param products 商品列表
     * @return 商品原始总价
     */
    public double calculateOriginalTotal(List<Product> products) {
        if (products == null || products.isEmpty()) {
            return 0.0;
        }
        // 使用 Stream 简化循环计算，提升代码可读性
        return products.stream().mapToDouble(Product::getPrice).sum();
    }

    /**
     * 计算用户等级对应的折扣价
     * @param originalTotal 商品原始总价
     * @param user 用户信息（含等级）
     * @return 等级折扣后的价格
     */
    public double applyUserLevelDiscount(double originalTotal, User user) {
        if (user == null) {
            return originalTotal; // 无用户信息，不享受折扣
        }
        return switch (user.getLevel()) {
            case 1 -> originalTotal * OrderConstant.USER_LEVEL_1_DISCOUNT;
            case 2 -> originalTotal * OrderConstant.USER_LEVEL_2_DISCOUNT;
            default -> originalTotal; // 其他等级无折扣
        };
    }

    /**
     * 计算优惠券对应的折扣价（后续可接入优惠券模块，扩展更多优惠券类型）
     * @param discountedTotal 等级折扣后的价格
     * @param couponId 优惠券 ID（null 表示无优惠券）
     * @return 叠加优惠券后的最终价格（不低于 0）
     */
    public double applyCouponDiscount(double discountedTotal, Integer couponId) {
        if (couponId == null) {
            return discountedTotal;
        }
        if (couponId.equals(OrderConstant.COUPON_ID_50)) {
            return Math.max(discountedTotal - OrderConstant.COUPON_AMOUNT_50, 0.0); // 避免价格为负
        }
        return discountedTotal; // 未知优惠券 ID，不享受折扣
    }
}

3. 订单服务类（OrderService.java）

package com.ecommerce.order.service;

import com.ecommerce.order.constant.OrderConstant;
import com.ecommerce.order.entity.Order;
import com.ecommerce.order.entity.Product;
import com.ecommerce.order.entity.User;
import com.ecommerce.order.repository.OrderRepository;
import com.ecommerce.order.repository.ProductRepository;
import com.ecommerce.order.repository.UserRepository;
import com.ecommerce.order.util.OrderPriceCalculator;
import lombok.RequiredArgsConstructor;
import lombok.extern.slf4j.Slf4j;
import org.springframework.stereotype.Service;
import org.springframework.util.CollectionUtils;
import java.util.List;
import java.util.Objects;
import java.util.stream.Collectors;

/**
 * 订单服务核心类，负责订单创建、状态更新的业务逻辑，依赖工具类实现细分功能
 */
@Service
@Slf4j // Lombok 注解，简化日志记录
@RequiredArgsConstructor // Lombok 注解，替代@Autowired，提升代码简洁性
public class OrderService {
    private final OrderRepository orderRepository;
    private final UserRepository userRepository;
    private final ProductRepository productRepository;
    private final OrderPriceCalculator priceCalculator;

    /**
     * 创建订单
     * @param userId 用户 ID（非 null）
     * @param productIds 商品 ID 列表（非空）
     * @param couponId 优惠券 ID（可为 null，表示不使用优惠券）
     * @return 创建成功的订单实体（含数据库自增 ID）
     * @throws IllegalArgumentException 当用户不存在、商品列表为空时抛出
     * @throws RuntimeException 当数据库操作失败时抛出
     */
    public Order createOrder(Long userId, List<Long> productIds, Integer couponId) {
        // 1. 数据校验（拆分独立逻辑，便于维护）
        validateCreateOrderParams(userId, productIds);

        // 2. 获取依赖数据（用户、商品）
        User user = userRepository.findById(userId).orElseThrow(() -> new IllegalArgumentException("用户不存在，userId: " + userId));
        List<Product> products = productRepository.findAllById(productIds);

        // 校验商品是否存在（避免传入无效商品 ID）
        if (products.size() != productIds.size()) {
            List<Long> existProductIds = products.stream().map(Product::getId).collect(Collectors.toList());
            List<Long> invalidIds = productIds.stream().filter(id -> !existProductIds.contains(id)).collect(Collectors.toList());
            throw new IllegalArgumentException("部分商品不存在，invalidProductIds: " + invalidIds);
        }

        // 3. 价格计算（依赖工具类，避免业务逻辑耦合）
        double originalTotal = priceCalculator.calculateOriginalTotal(products);
        double levelDiscountedTotal = priceCalculator.applyUserLevelDiscount(originalTotal, user);
        double finalTotal = priceCalculator.applyCouponDiscount(levelDiscountedTotal, couponId);
        log.info("订单价格计算完成，userId: {}, 原始总价：{}, 等级折扣后：{}, 最终总价：{}", userId, originalTotal, levelDiscountedTotal, finalTotal);

        // 4. 构建订单实体并保存
        Order order = new Order();
        order.setUserId(userId);
        // 存储商品 ID 为逗号分隔字符串（后续可优化为关联表，此处保持原逻辑兼容）
        order.setProductIds(productIds.stream().map(String::valueOf).collect(Collectors.joining(",")));
        order.setTotalPrice(finalTotal);
        order.setStatus(OrderConstant.ORDER_STATUS_PENDING); // 使用常量，避免硬编码

        try {
            return orderRepository.save(order);
        } catch (Exception e) {
            log.error("订单保存失败，userId: {}, productIds: {}", userId, productIds, e);
            throw new RuntimeException("订单创建失败，请重试", e);
        }
    }

    /**
     * 更新订单状态
     * @param orderId 订单 ID（非 null）
     * @param status 目标状态（需为 OrderConstant 中定义的合法状态）
     * @throws IllegalArgumentException 当订单不存在、状态不合法时抛出
     */
    public void updateOrderStatus(Long orderId, Integer status) {
        // 1. 校验订单是否存在
        Order order = orderRepository.findById(orderId).orElseThrow(() -> new IllegalArgumentException("订单不存在，orderId: " + orderId));

        // 2. 校验状态合法性（避免传入无效状态值）
        if (!isValidOrderStatus(status)) {
            throw new IllegalArgumentException("无效订单状态，status: " + status + "，合法状态：" + List.of(OrderConstant.ORDER_STATUS_PENDING, OrderConstant.ORDER_STATUS_PAID, OrderConstant.ORDER_STATUS_SHIPPED, OrderConstant.ORDER_STATUS_COMPLETED, OrderConstant.ORDER_STATUS_CANCELLED));
        }

        // 3. 更新状态并保存
        order.setStatus(status);
        orderRepository.save(order);
        log.info("订单状态更新完成，orderId: {}, 旧状态：{}, 新状态：{}", orderId, order.getStatus(), status);
    }

    /**
     * 校验订单创建的入参合法性
     * @param userId 用户 ID
     * @param productIds 商品 ID 列表
     * @throws IllegalArgumentException 当参数不合法时抛出
     */
    private void validateCreateOrderParams(Long userId, List<Long> productIds) {
        if (Objects.isNull(userId)) {
            throw new IllegalArgumentException("用户 ID 不能为空");
        }
        if (CollectionUtils.isEmpty(productIds)) {
            throw new IllegalArgumentException("商品列表不能为空");
        }
    }

    /**
     * 校验订单状态是否合法
     * @param status 待校验的状态值
     * @return true-合法，false-不合法
     */
    private boolean isValidOrderStatus(Integer status) {
        if (Objects.isNull(status)) {
            return false;
        }
        List<Integer> validStatusList = List.of(OrderConstant.ORDER_STATUS_PENDING, OrderConstant.ORDER_STATUS_PAID, OrderConstant.ORDER_STATUS_SHIPPED, OrderConstant.ORDER_STATUS_COMPLETED, OrderConstant.ORDER_STATUS_CANCELLED);
        return validStatusList.contains(status);
    }
}

b. 重构方案说明

1. 结构调整：
   • 拆分职责：将原 OrderService 中的'价格计算'拆分为 OrderPriceCalculator 工具类，'常量定义'拆分为 OrderConstant 类，使 OrderService 仅聚焦'订单业务流程'（创建、状态更新），符合单一职责原则；
   • 提取私有方法：将'入参校验''状态合法性校验'提取为 validateCreateOrderParams、isValidOrderStatus 方法，避免主流程代码冗长，提升可维护性。
2. 规范适配：
   • 命名规范：所有类/方法/变量名遵循 Google Java 规范（如 OrderPriceCalculator 为大驼峰，calculateOriginalTotal 为小驼峰），避免歧义；
   • 注释规范：每个类、公共方法均添加 Javadoc 注释，说明功能、参数、异常；关键业务逻辑（如价格计算、异常处理）添加单行注释；
   • 异常处理：替换原有的 System.out 打印，使用 @Slf4j 记录日志；用 orElseThrow 替代 get() 避免空指针异常；明确抛出 IllegalArgumentException（参数错误）、RuntimeException（业务异常），便于调用方捕获处理；
   • 依赖注入：使用 Lombok 的 @RequiredArgsConstructor 替代 @Autowired，减少模板代码。
3. 性能优化：
   • 消除硬编码：将订单状态、折扣比例、优惠券面值定义为常量，后续修改无需改动业务代码；
   • 数据查询优化：用 findAllById 替代循环 findById，减少数据库查询次数；
   • 逻辑简化：用 Stream API 替代 for 循环计算商品总价，代码更简洁。

c. 风险提示

1. 测试重点：
   • 功能一致性测试：需验证重构后 createOrder、updateOrderStatus 方法的输入输出与重构前一致，避免影响现有调用方；
   • 异常场景测试：重点测试'用户不存在''商品不存在''无效优惠券 ID''无效订单状态'等场景，确保异常抛出符合预期；
   • 边界值测试：如商品总价为 0、优惠券抵扣后价格为负（需验证是否返回 0）、用户等级为 3（无折扣）等场景。
2. 后续优化方向：
   • 商品 ID 存储：当前用字符串存储商品 ID，后续可改为'订单 - 商品'关联表（如 OrderProduct），支持多对多关系，提升查询效率；
   • 优惠券模块集成：当前通过 couponId 硬编码判断，后续可接入优惠券模块，通过 CouponRepository 查询优惠券信息，提升扩展性；
   • 分布式事务：若后续订单创建需调用库存扣减、积分增加等跨模块操作，需引入 Seata 等框架保障分布式事务一致性。

（三）专家版 Prompt：适用于遗留系统重构与架构适配

核心场景：技术负责人处理大型遗留系统重构（如几十万行代码的旧系统），需考虑'架构兼容性'（如从单体架构迁移到微服务）、'历史数据迁移'、'灰度发布'等复杂需求，同时平衡重构成本与业务稳定性。 设计逻辑：在进阶版基础上，增加'架构目标''约束条件''风险评估'要求，让模型不仅生成代码重构方案，还提供'工程落地策略'（如迁移步骤、测试方案、回滚机制）。 模板结构：

指令：作为一名资深架构师，拥有 [X 年] 遗留系统重构经验，请帮我设计某 [系统名称] 的重构方案，需兼顾代码可读性提升与业务稳定性。
系统背景：
1. 系统现状：[说明系统规模、架构、技术栈，如'单体架构，Java 8 + Spring MVC，代码量 50 万行，无单元测试，数据库为 Oracle 11g']；
2. 业务痛点：[说明当前存在的问题，如'代码耦合严重，新增功能需修改多个模块；部署周期长，每次发布需停服 2 小时']；
3. 重构目标：[说明架构目标，如'拆分微服务（用户中心、订单中心、支付中心）；代码符合 Clean Architecture；支持灰度发布']；
4. 约束条件：[说明不可突破的约束，如'重构期间业务不能中断；历史数据需 100% 迁移；需兼容旧版 API（支持 v1/v2 版本并存）']；
重构要求：
1. 代码层重构：针对 [核心模块，如'订单模块']，提供'现状分析 - 重构方案 - 代码示例'，重点解决'可读性差、耦合高'问题；
2. 架构层重构：设计微服务拆分方案（含服务边界、接口定义、依赖关系）；
3. 工程落地：提供分阶段迁移步骤（如'调研期 - 设计期 - 开发期 - 测试期 - 灰度期 - 全量期'），明确每个阶段的输出物、责任人、时间节点；
4. 风险管控：识别重构中的关键风险（如'数据不一致''服务调用超时'），提供应对策略（如'双写数据''熔断降级'）；
5. 输出格式：
   a. 系统现状分析报告（含问题清单、优先级）；
   b. 核心模块重构代码示例（按文件拆分）；
   c. 微服务架构设计图（文字描述或 Mermaid 语法）；
   d. 分阶段落地计划（表格形式）；
   e. 风险评估与应对矩阵。

注：专家版 Prompt 的输出通常是'方案文档 + 代码示例'的组合，需结合具体系统的详细信息（如数据库表结构、接口文档）才能生成精准方案，此处不展开完整案例，重点在于体现'架构思维'与'工程落地'的结合——重构建议 Prompt 不仅是代码优化工具，更是架构升级的辅助决策工具。

不同编程语言的重构建议 Prompt 适配技巧

LLM 对不同编程语言的理解能力存在差异（如对 Python、Java 的支持优于小众语言），且各语言的'可读性规范''重构痛点'不同。需根据语言特性调整 Prompt 的'指令细节''示例风格'，确保模型生成符合语言习惯的方案。以下针对 4 种主流语言，提供适配技巧与 Prompt 片段：

（一）Python：聚焦'PEP 8 规范'与'简洁性'

语言特性：动态类型、缩进敏感、强调'代码可读性'（PEP 8 规范），常见重构痛点为'函数过长''参数过多''类型注解缺失'。 适配技巧：

1. 在 Prompt 中明确要求'符合 PEP 8 规范'（如缩进 4 个空格、最大行宽 79 字符、导入顺序）；
2. 要求添加'类型注解'（Python 3.5+ 特性），提升代码可维护性；
3. 鼓励使用 Python 特有的语法（如列表推导式、生成器、装饰器）简化逻辑。

Prompt 片段示例：

指令：作为一名熟悉 PEP 8 规范的 Python 资深开发工程师，请重构以下代码：
原始代码：[待重构的 Python 代码]
重构要求：
1. 符合 PEP 8 规范：缩进 4 个空格，函数/类之间空 2 行，导入顺序为'标准库->第三方库->自定义库'；
2. 添加完整类型注解（参数、返回值、局部变量），使用 typing 模块（如 List、Dict）；
3. 简化逻辑：优先使用列表推导式、生成器表达式替代 for 循环；用装饰器处理重复逻辑（如日志、缓存）；
4. 消除代码异味：拆分过长函数（>50 行）、过多参数（>5 个）；用 dataclass 替代普通类存储数据。

（二）Java：聚焦'设计模式'与'框架规范'

语言特性：静态类型、面向对象、依赖框架（如 Spring Boot），常见重构痛点为'类职责混乱''接口设计不清晰''异常处理不规范'。 适配技巧：

1. 在 Prompt 中指定'设计模式'（如用'工厂模式'替代复杂 if-else，用'策略模式'处理多种算法）；
2. 要求符合框架规范（如 Spring Boot 的'分层架构'：Controller->Service->Repository）；
3. 强调'接口隔离'，避免一个接口包含过多方法。

Prompt 片段示例：

指令：作为一名熟悉 Spring Boot 分层架构和设计模式的 Java 工程师，请重构以下代码：
原始代码：[待重构的 Java 代码]
重构要求：
1. 架构分层：确保代码符合'Controller（接收请求）->Service（业务逻辑）->Repository（数据访问）'分层，避免跨层调用；
2. 设计模式：用'策略模式'重构多种支付方式（如支付宝、微信支付）的逻辑，避免 if-else 判断；
3. 接口规范：定义清晰的 Service 接口（如 PaymentService），实现类（AlipayService、WechatPayService）遵循接口契约；
4. 代码规范：符合 Google Java 规范，使用 Lombok 简化 POJO，添加完整 Javadoc 注释。

（三）JavaScript/TypeScript：聚焦'模块化'与'异步逻辑'

语言特性：动态类型（TypeScript 为静态）、异步编程（Promise、async/await），常见重构痛点为'回调地狱''模块依赖混乱''类型不明确（JavaScript）'。 适配技巧：

1. 要求用'ES6+ 模块化'（import/export）替代 CommonJS（require），明确模块边界；
2. 要求用'async/await'替代嵌套 Promise，消除回调地狱；
3. TypeScript 需强调'接口定义''泛型使用'，提升类型安全性。

Prompt 片段示例：

指令：作为一名熟悉 TypeScript 和 Node.js 的前端/后端工程师，请重构以下代码：
原始代码：[待重构的 JS/TS 代码]
重构要求：
1. 模块化：使用 ES6 import/export 拆分代码，每个模块仅暴露必要的 API，避免全局变量污染；
2. 异步逻辑：用 async/await 替代嵌套 Promise，添加 try/catch 处理异步异常；
3. TypeScript 规范：定义清晰的接口（interface）或类型别名（type），为所有函数/变量添加类型注解；
4. 代码简化：用解构赋值、扩展运算符（...）替代繁琐的对象/数组操作；用 Array 方法（map、filter、reduce）替代 for 循环。

（四）Go：聚焦'简洁性'与'并发安全'

语言特性：静态类型、语法简洁、原生支持并发（goroutine、channel），常见重构痛点为'错误处理冗余''并发安全问题''函数参数过多'。 适配技巧：

1. 要求遵循'Go 语言规范'（如变量名简短但明确、函数名小写（包内可见）/大写（导出））；
2. 要求优化错误处理（用 errors.Wrap 添加错误上下文，避免直接返回 fmt.Errorf）；
3. 强调'并发安全'：若涉及 goroutine，需说明同步机制（如 mutex、channel），避免数据竞争。

Prompt 片段示例：

指令：作为一名熟悉 Go 语言规范和并发编程的工程师，请重构以下代码：
原始代码：[待重构的 Go 代码]
重构要求：
1. 代码规范：遵循 Go 官方规范，变量名（如 userID 而非 userId）、函数名（导出函数首字母大写）符合习惯；
2. 错误处理：使用 github.com/pkg/errors 的 Wrap/Unwrap 添加错误上下文，便于问题定位；避免忽略错误（如 _ 接收错误返回值）；
3. 并发安全：若使用 goroutine，需通过 sync.Mutex 或 channel 保证数据同步，避免数据竞争；
4. 函数优化：拆分参数过多（>4 个）的函数，用结构体（struct）封装相关参数；消除重复代码，提取公共函数。

重构建议 Prompt 的常见问题与解决方案

在实际使用中，重构建议 Prompt 可能出现'模型理解偏差''方案不可执行''忽略业务约束'等问题。以下总结 6 类常见问题，提供对应的'问题表现 - 原因分析 - 解决方案'：

章节总结与实践建议

（一）核心要点回顾

1. 代码可读性的本质：是'让他人（或未来的自己）能快速理解代码功能、逻辑、意图'的属性，需从命名、函数设计、逻辑简化、注释、复用性 5 个维度评估；
2. 重构建议 Prompt 的核心结构：需包含'明确指令（做什么）+ 上下文信息（代码背景、技术栈、约束）+ 输出要求（格式、内容）'，不同复杂度场景对应基础版、进阶版、专家版模板；
3. 语言适配原则：需根据 Python、Java、JavaScript/TypeScript、Go 等语言的特性，调整 Prompt 中的'规范要求''语法偏好'，确保生成符合语言习惯的方案；
4. 风险管控意识：重构不仅是代码优化，还需考虑'功能一致性''兼容性''测试覆盖'，避免因重构引入新问题。

（二）实践建议

1. 从小规模场景入手：新手可先使用基础版 Prompt 重构独立函数/代码块（如单个 Python 函数、Java 方法），熟悉模型的输出风格后，再逐步尝试模块级、架构级重构；
2. 提供充分上下文：在使用 Prompt 时，尽可能补充'项目技术栈''现有依赖''业务规则''约束条件'等信息，减少模型的猜测成本，提升方案精准度；
3. 人工审核不可少：LLM 生成的重构方案可能存在'依赖不存在''忽略业务细节'等问题，需人工审核方案的可行性，尤其是核心业务模块的重构；
4. 积累专属 Prompt 模板：针对团队常用的技术栈（如'Java + Spring Boot''Python + Django'）、行业场景（如电商、金融），积累定制化的 Prompt 模板，提升后续重构效率；
5. 结合工具链落地：将重构方案与代码质量工具（如 SonarQube：检测代码异味）、测试工具（如 JUnit、PyTest：验证功能一致性）结合，形成'Prompt 生成方案→工具检测→人工审核→落地执行'的闭环。

通过本章的学习，读者应能掌握'从识别代码可读性问题，到设计精准 Prompt，再到落地重构方案'的全流程方法。重构是一个持续迭代的过程，需在'代码可读性'与'业务稳定性'之间找到平衡，而重构建议 Prompt 则是提升这一过程效率的重要工具。

课后练习

练习 1：基础级——重构 Python 数据过滤函数

1. 待重构代码（问题：命名模糊、无注释、嵌套冗余）：

def f2(lst):
    new_lst = []
    for item in lst:
        if isinstance(item, dict):
            if 'age' in item:
                if item['age'] >= 18:
                    new_lst.append(item)
    return new_lst

2. 任务：使用基础版 Prompt 重构该函数，要求：
   • 优化命名（符合 Python 蛇形命名法）；
   • 简化嵌套逻辑（≤2 层）；
   • 补充完整注释（函数文档注释 + 关键逻辑注释）；
   • 生成重构后的代码及重构点说明。

练习 2：进阶级——重构 JavaScript 异步请求函数

1. 待重构代码（问题：回调地狱、无错误处理、类型不明确）：

function getUsers(callback) {
    fetch('https://api.example.com/users').then(res => res.json()).then(users => {
        fetch('https://api.example.com/roles').then(res => res.json()).then(roles => {
            const userWithRoles = users.map(user => {
                const role = roles.find(r => r.id === user.roleId);
                return {...user, role: role ? role.name : 'unknown'};
            });
            callback(userWithRoles);
        }).catch(err => console.log(err));
    }).catch(err => console.log(err));
}

2. 任务：使用进阶版 Prompt 重构该函数，要求：
   • 用 async/await 替代嵌套 Promise，消除回调地狱；
   • 完善错误处理（添加 try/catch，记录详细日志，明确抛出异常）；
   • 若使用 TypeScript，添加接口定义（User、Role、UserWithRole）；
   • 生成重构后的代码、重构方案说明、测试用例（正常场景、接口报错场景）。

练习 3：专家级——设计 Java 电商库存模块重构方案

1. 模块背景：
   • 功能：电商库存模块，负责商品库存查询、扣减、归还，依赖商品模块（获取商品信息）、订单模块（订单取消时归还库存）；
   • 技术栈：Java 11 + Spring Boot 2.7，使用 Redis 缓存库存，MySQL 存储库存明细；
   • 现有问题：库存扣减无锁机制（并发下单导致超卖）、代码耦合（库存逻辑与订单逻辑混合）、无异常重试机制；
2. 任务：使用专家版 Prompt 设计重构方案，要求：
   • 代码层：拆分库存逻辑为独立 Service（StockService），实现'查询 - 扣减 - 归还'功能，添加 Redis 分布式锁防止超卖；
   • 架构层：明确库存模块与商品、订单模块的接口定义（如'订单创建时调用 StockService.deductStock'）；
   • 工程落地：提供分阶段实施计划（调研期、开发期、测试期、灰度期）；
   • 风险管控：识别'超卖''缓存与数据库不一致''接口超时'等风险，提供应对策略。

练习参考答案思路点拨

练习 1 思路：

• 函数名改为 filter_adult_users（明确'筛选成年用户'）；
• 参数名 lst 改为 user_list（明确为用户列表）；
• 用列表推导式简化 3 层嵌套为 1 层（[user for user in user_list if isinstance(user, dict) and 'age' in user and user['age'] >= 18]）；
• 补充文档注释，说明函数功能（筛选包含 age 且 age≥18 的用户字典）、参数（user_list：用户字典列表）、返回值（符合条件的用户列表）。

练习 2 思路：

• 函数名改为 getUsersWithRoles（明确'获取带角色的用户'）；
• 用 async/await 重构异步逻辑，添加 try/catch 捕获网络错误、数据处理错误，用 console.error 记录日志；
• TypeScript 接口定义：interface User { id: number; name: string; roleId: number }，interface Role { id: number; name: string }，interface UserWithRole extends User { role: string }；
• 测试用例：正常场景（接口返回正确数据，验证是否添加 role 字段）、接口报错场景（模拟 API 返回 404，验证是否捕获异常并日志）。

练习 3 思路：

• 代码层：StockService 中添加 deductStock（扣减库存，用 Redis 分布式锁）、restoreStock（归还库存）、getStock（查询库存）方法；定义 StockConstant 类存储 Redis 键前缀、锁超时时间等常量；
• 架构层：库存模块对外提供 REST 接口（如 /api/v1/stock/deduct），订单模块通过 Feign 调用；商品模块提供 /api/v1/product/get 接口供库存模块查询商品是否存在；
• 工程落地：调研期（1 周，输出库存模块现状报告）→开发期（2 周，完成代码重构）→测试期（1 周，完成功能、并发、异常测试）→灰度期（1 周，先对 10% 订单流量生效，无问题后全量）；
• 风险管控：超卖（用 Redis 分布式锁 + 数据库乐观锁双重保障）、缓存不一致（扣减库存时先更数据库，再更缓存；归还库存时先更缓存，再更数据库）、接口超时（添加 Feign 熔断降级，超时时间设为 3 秒）。