方法重载设计应以调用方易懂为核心，优先用语义明确的类型（如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。如果重载方法刚好落在这些提升路径上，字面量调用就可能失败。
立即学习“Java免费学习笔记（深入）”；
- ❌ 避免：
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()，比七八个构造器更直观、更难出错
