方法重载设计应以调用方易懂为核心，优先用语义明确的类型（如File/Path/URL）、参数数量或顺序表达意图，避免隐式类型提升歧义，构造器宜配合工厂方法或Builder提升可读性。

设计方法重载的参数列表，关键不是“能编译通过”，而是让调用方一眼看懂该用哪个、为什么用这个。清晰易懂的核心在于降低认知负担，避免歧义和隐式转换。

用语义差异代替类型微调

别只靠 int 和 Integer、String 和 CharSequence 这类细微类型差别来区分重载。这类设计容易引发装箱歧义（比如传 null 时编译失败），也难看出意图。

• ✅ 推荐：用有明确业务含义的类型，比如 process(File file)、process(Path path)、process(URL url) —— 类型不同，用途一目了然
• ✅ 或者用封装类表达意图：load(UserId id) 和 load(Username name)，比 load(long) 和 load(String) 更安全、更自解释

优先用参数数量或顺序显式表达意图

当功能层级天然有主次之分时，参数数量或顺序就是最直观的区分方式。

java-api-doc-generator

分析 Java Spring Boot 后端 Controller 代码，自动生成 Markdown 格式的接口文档。当用户说“生成 Java 接口文档”、“生成 API 文档”、“从 Spring 代码生成文档”时触发。

下载

• ✅ 例如日志方法：log(String msg)（基础）、log(String msg, Throwable t)（带异常）、log(Level level, String msg)（指定级别）——数量增加 = 功能增强，符合直觉
• ✅ 再如构造场景：connect(Host host, Port port) 和 connect(Port port, Host host) 只有在两者类型完全不同、且调用上下文常需交换位置时才合理；否则建议统一顺序，或改用 Builder

避开隐式类型提升带来的模糊地带

Java 会自动把 byte、short 提升为 int，把 int 提升为 long 或 double。如果重载方法刚好落在这些提升路径上，字面量调用就可能失败。

• ❌ 避免：handle(short s) + handle(long l) → 调用 handle(1) 编译报错（1 可升为 short 也可升为 long）
• ✅ 安全做法：只保留一个“自然匹配”的类型，比如只留 handle(int i)；或者用完全不兼容的类型，如 handle(LocalDate date) 和 handle(Duration dur)

构造器和工厂方法优先考虑可读性而非重载数量

构造器重载过多，尤其当多个参数都是 String 时，调用方极易传错顺序，且 IDE 提示信息有限。

• ✅ 推荐组合：new User(String name, int age)（必要字段）+ 静态工厂方法 User.fromEmail(String email)、User.fromJson(String json)
• ✅ 复杂对象用 Builder：User.builder().name("Alice").age(30).build()，比七八个构造器更直观、更难出错

Java免费学习笔记：立即使用
解锁 Java 大师之旅：从入门到精通的终极指南