JavaDoc 的 @param 标签必须紧邻对应方法（而非类）声明上方，且方法参数名需与实际签名严格一致；若注释写在类体外或参数不可见位置，IDE 将报“Cannot resolve symbol”错误。
javadoc 的 `@param` 标签必须紧邻对应方法（而非类）声明上方，且方法参数名需与实际签名严格一致；若注释写在类体外或参数不可见位置，ide 将报“cannot resolve symbol”错误。
在 IntelliJ IDEA 中遇到 Cannot resolve symbol 'multipartFile' 或 Cannot resolve symbol 'dir' 的提示，并非代码逻辑错误，而是 JavaDoc 文档注释（/* ... /）的位置不合法导致的解析失败。
根本原因：
您将包含 @param 的 JavaDoc 注释写在了 类定义外部（即 public class UploadServiceImp { 之前），此时 Javadoc 工具和 IDE 无法将其关联到任何具体方法——因为类本身没有参数，而其内部方法 uploadImg(...) 在语法上尚未被该注释“覆盖”。Javadoc 规范明确要求：@param 只能用于可带参数的程序元素（如方法、构造器），且注释块必须直接位于该元素的声明之前，中间不能有空行或其它语句。
✅ 正确写法（注释紧贴方法声明）：
public class UploadServiceImp {
/**
* 上传图片文件到指定目录
* <p>
* MultipartFile 是 Spring MVC 提供的文件上传封装类，
* 底层通过调用 HttpServletRequest.getInputStream() 实现数据读取。
*
* @param multipartFile 上传的文件对象（非 null）
* @param dir 目标子目录名（如 "avatar"），用于拼接存储路径
* @return 成功返回 Code.SAVE_OK，失败返回 Code.SAVE_ERR
*/
public Integer uploadImg(MultipartFile multipartFile, String dir) {
File targetFile = new File("F://temp/" + dir);
try {
multipartFile.transferTo(targetFile);
return Code.SAVE_OK;
} catch (IOException e) {
e.printStackTrace();
return Code.SAVE_ERR;
}
}
}⚠️ 注意事项：
- @param 后的参数名（如 multipartFile）必须与方法签名中完全一致（区分大小写、无下划线差异）；
- 注释块与方法之间不得插入空行或字段/注解等其他代码，否则 IDEA 可能断开关联；
- 若方法重载，每个重载版本都需独立配备注释；
- 建议启用 IDEA 的 JavaDoc 检查（Settings → Editor → Inspections → Java → JavaDoc）以实时提示缺失或错位标签。
修复后，IDEA 将立即识别参数并提供完善的悬停文档、代码补全及生成 Javadoc HTML 的支持。遵循这一位置规范，是编写可维护、可生成标准 API 文档的专业 Java 代码的基础要求。
立即学习“Java免费学习笔记（深入）”；
