Java接口参数设计，如何兼顾规范与灵活？

在Java接口设计中,参数方案的设计直接影响代码的可读性、可维护性和扩展性，合理的参数设计需要兼顾业务逻辑、调用方体验以及后续迭代需求，以下从多个维度详细探讨Java接口参数的设计方案。

（图片来源网络，侵删）

参数的基本设计原则

单一职责原则：每个参数应具备明确的业务含义，避免将多个不相关的数据封装在一个参数中，用户注册接口应分别接收用户名、密码、邮箱等独立参数，而非将所有信息塞进一个Map对象。
必要性原则：仅包含接口实现必需的参数，避免冗余参数，查询订单详情接口无需接收用户性别等无关信息。
可扩展性原则：通过合理的参数结构设计，支持未来新增参数而不破坏现有调用，使用DTO对象而非固定参数列表，便于添加新字段。

基本类型与包装类型
- 基本类型（如int、boolean）适用于明确存在且无null需求的场景，如分页页码（pageNum）。
- 包装类型（如Integer、Boolean）适用于参数可能为null的场景，如筛选条件（status可为null表示全部）。
  示例对比：
```
// 不推荐：基本类型无法表达“未传递”状态
public void updateOrder(int status);  
// 推荐：包装类型支持null值
public void updateOrder(Integer status);  
```
自定义对象（DTO）
当参数数量超过3个或存在业务关联性时，建议封装为DTO对象，创建订单接口可定义OrderCreateDTO，包含商品ID、数量、收货地址等字段。
优势：
- 参数结构清晰,避免方法签名过长；
- 便于统一校验和日志记录；
- 支持新增字段而不影响调用方。
集合与数组类型
- 使用泛型集合（如List<String>）而非数组（如String[]），因为集合支持动态长度且提供更多操作方法。
- 明确集合的业务含义,如List<Long> userIds比List<?>更易理解。

注解校验：通过JSR 303验证规范（如Hibernate Validator）添加校验注解，减少手动校验代码。
示例：
（图片来源网络，侵删）
```
public class UserDTO {
    @NotBlank(message = "用户名不能为空")
    private String username;
    @Email(message = "邮箱格式错误")
    private String email;
}
```
业务规则校验：对于复杂业务逻辑（如库存校验），应在接口实现层或通过AOP统一处理，避免在参数对象中混合校验逻辑。

避免使用Map作为参数：
- 缺乏类型安全,编译期无法发现错误；
- 调用方需自行维护key的含义,易出错。
  替代方案：定义明确的DTO对象。
参数默认值与可选参数：
- 对于可选参数,使用方法重载或默认参数值（Java 14+支持）。
  示例：
```
// 重载方式
public void search(String keyword);  
public void search(String keyword, Integer pageNum);  
```
分页参数标准化：
统一分页参数结构，避免接口间参数不一致。
推荐结构：
| 参数名 | 类型 | 说明 |
|———-|——–|——————–|
| pageNum | int | 当前页码（从1开始）|
| pageSize | int | 每页条数 |
| keyword | String | 搜索关键词 |

敏感参数处理：
- 密码、身份证号等敏感信息应加密传输（如HTTPS+AES加密）；
- 避免在日志中直接打印完整参数,可脱敏处理。
参数防篡改：
- 关键接口（如支付）需添加签名参数，通过密钥验证参数完整性；
- 使用不可变对象（如通过final修饰DTO字段）防止参数被意外修改。

向后兼容：新增参数时保持旧参数列表不变，通过DTO扩展字段。

// V1版本
public class OrderV1 { private Long productId; }  
// V2版本新增字段
public class OrderV2 extends OrderV1 { private String promotionCode; }

通过Swagger（OpenAPI）生成接口文档，明确标注：

参数的业务含义。
示例：

@ApiOperation("创建订单")  
public void createOrder(@RequestBody @Valid OrderCreateDTO order)