Java参数结构案例怎么规范

本文目录导读：

1. 核心原则：参数对象模式
2. 特定场景规范案例
3. 必须遵守的编码规范
4. 最规范的Java参数结构

在Java中规范参数结构，核心目的是为了解决方法参数过多、类型不明确、难以扩展和维护的问题，最常见的规范方案是使用参数对象模式以及遵循一些编码规范。

以下是几种常见的规范案例,从基础到进阶：

核心原则：参数对象模式

场景： 当一个方法需要的参数超过3个,或者参数之间存在逻辑关联时。

反例（不规范）：

// 糟糕：参数太多，容易搞混顺序，扩展困难
public class OrderService {
    public boolean createOrder(
        Long userId, 
        String productName, 
        int quantity, 
        double price, 
        String address, 
        String phone, 
        String remark
    ) {
        // ... 逻辑
        return true;
    }
}

正例（规范）：

第一步：定义参数对象（DTO/POJO）

这个类专门用于承载这些参数，通常是一个Java Bean（包含getter/setter或使用record）。

// 方式一：传统Java Bean (适用于需要复杂逻辑的)
public class CreateOrderRequest {
    private Long userId;
    private String productName;
    private int quantity;
    private double price;
    private String address;
    private String phone;
    private String remark;
    // Getters and Setters ... 
}
// 方式二：Java 16+ Record (适用于简单的数据传输，不可变)
// public record CreateOrderRequest(
//     Long userId,
//     String productName,
//     int quantity,
//     double price,
//     String address,
//     String phone,
//     String remark
// ) {}

第二步：方法调用升级

public class OrderService {
    // 规范：方法只接收一个参数对象，易于阅读和扩展
    public boolean createOrder(CreateOrderRequest request) {
        // 直接使用 request.getUserId(), request.getProductName() 等
        return true;
    }
    // 调用方
    public void callService() {
        CreateOrderRequest request = new CreateOrderRequest();
        request.setUserId(1001L);
        request.setProductName("Java 编程思想");
        // ... setter 赋值
        // 也可以使用 Builder 模式来构建
        CreateOrderRequest requestBuilder = CreateOrderRequestBuilder.builder()
                .userId(1001L)
                .productName("Java 编程思想")
                .build();
        createOrder(requestBuilder);
    }
}

特定场景规范案例

查询参数（分页+条件）

规范： 将分页参数和业务查询条件分开，或合并为一个Query对象。

// 推荐：使用通用分页参数 + 业务查询条件对象
public class UserQueryParam {
    // 继承或组合分页信息
    private int pageNum = 1;
    private int pageSize = 10;
    private String name;
    private String email;
    private Integer status;
    // Getters & Setters ...
}
// Service 层
public PageResult<User> searchUsers(UserQueryParam param) {
    // 使用 param.getPageNum(), param.getName() 构建 SQL 或查询
}

配置参数（Builder模式）

当一个参数对象内部字段很多，且有很多默认值时，推荐使用Builder模式。

// 规范：使用 Lombok 或手写 Builder
@Builder  // 使用 Lombok 自动生成 Builder
public class HttpClientConfig {
    private int connectTimeout = 5000; // 默认值
    private int readTimeout = 5000;
    private boolean retryEnabled = false;
    private int maxRetries = 3;
    private String baseUrl;
}
// 使用
HttpClientConfig config = HttpClientConfig.builder()
        .baseUrl("https://api.example.com")
        .connectTimeout(10000)
        .build(); // retryEnabled 使用默认 false

过滤/类型参数（枚举）

当参数是有限的几种类型时，用Enum代替String或int。

// 规范：强类型枚举，而不是魔法值
public enum SortOrder {
    ASC, DESC
}
public class ProductQuery {
    private String keyword;
    private SortOrder sortOrder; // 强制调用方传入 ASC 或 DESC
    // ...
}
// 反例：public void search(String sortOrder)  // 调用方可能传入 "asc" "ascending" "1" 等，难以处理

必须遵守的编码规范

除了使用对象封装,还有一些语法层面的规范：

避免 Map 作为参数

• 反例： public void updateUser(Map<String, Object> params)

  原因：编译器无法校验类型，容易拼写错误,难以追踪来源。

• 正例： 使用上面提到的具体DTO。

参数顺序规则

• 如果必须使用多个基本参数（不推荐），请遵循：
  1. 长度/容量 在前，具体数据 在后（arraycopy(Object src, int srcPos, Object dest, int destPos, int length)）。
  2. 核心业务参数 在前，可选标志位 在后。
  3. 回调接口 通常放在最后（ExecutorService.submit(Callable task)）。

避免过长的参数列表

• 规范： 超过3个参数，且没有明显逻辑分组时,立刻考虑封装为一个类。
• IDE 检查： 大部分 IDE（如 Idea）和代码检查工具（SonarLint, Checkstyle）会警告“Too many parameters”。

布尔参数分离原则

• 反例： processOrder(order, true) // 调用时不知道 true 代表什么。

• 正例：

  // 拆分为两个命名清晰的方法
  processOrder(order);
  processOrderAndNotify(order);
  // 或者使用参数对象/枚举
  public void processOrder(Order order, boolean sendNotification) // 勉强接受，但不如方法名清晰

接口（Interface）参数规范（依赖倒置）

当参数类型是具体实现类时，应尽量依赖抽象。

• 反例： public void execute(ArrayList<String> list) -> 限制了只能传入 ArrayList。
• 正例： public void execute(List<String> list) -> 支持 ArrayList, LinkedList 等。
• 更佳： 视情况使用最抽象的接口 Collection 或 Iterable（如果需要迭代）。

最规范的Java参数结构

1. 首选： 使用专门的参数对象（DTO/Record），配合 Builder模式（特别是参数很多时）。
2. 次选（极少参数且语义清晰）： 使用基础类型（String, int），并严格遵守顺序规则（标识 > 类型 > 回调）。
3. 禁止： 使用 Map<String, Object> 或超过 5 个散乱的参数。
4. 增强： 配合 Lombok (@Builder, @Data) 或 IDE自动生成,减少样板代码。