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 { 上方），而 @param 只能用于描述方法、构造函数或字段的参数/属性。类本身没有形参，因此 IDE 无法将 @param multipartFile 等标签与任何有效作用域关联，从而报“无法解析符号”。
✅ 正确做法：将 JavaDoc 注释直接放在目标方法声明的正上方，且紧邻方法签名，中间不得插入空行或其它语句。
当用户要求为 Java 代码添加注释、修改注释、审查注释、整理注释格式，或要求按照代码注释规范处理 Java 文件时，使用本技能。本技能用于统一生成和维护 Java 类注释模板、按 Git 对比 release 判断版本号、补充每行代码上方中文块注释、调整注释空行规则，并保持 Java 文件 UTF-8 无 BOM 编码。典型触发场景包括：补充类注释、更新 @version、检查 @author 来源、整理行尾注释、把注释放到代码上一行、检查注释是否符合规范、构建前检查 Java 注释风格。
以下是修正后的代码示例：
public class UploadServiceImp {
/**
* 文件上传方法
* <p>
* MultipartFile 是 Spring MVC 提供的文件上传封装类，
* 底层通过调用 HttpServletRequest.getInputStream() 实现流式读取。
*
* @param multipartFile 接收的上传文件对象（不能为空）
* @param dir 指定保存子目录（如 "avatar/"），将拼接到基础路径后
* @return 成功返回 Code.SAVE_OK，失败返回 Code.SAVE_ERR
*/
public Integer uploadImg(MultipartFile multipartFile, String dir) {
// 指定文件上传的目录（注意：生产环境应避免硬编码绝对路径，建议使用 Resource 或配置化路径）
File targetFile = new File("F://temp//" + dir);
try {
multipartFile.transferTo(targetFile);
return Code.SAVE_OK;
} catch (IOException e) {
e.printStackTrace();
return Code.SAVE_ERR;
}
}
}</p>
⚠️ 注意事项：
- JavaDoc 必须严格遵循「注释紧贴被注释元素」原则：方法的 JavaDoc → 方法签名正上方；字段的 JavaDoc → 字段声明正上方。
- 类级 JavaDoc 可使用 @author、@version、@see 等标签，但禁止使用 @param（类无参数）。
- IntelliJ 默认启用 JavaDoc 检查（Settings → Editor → Inspections → Java → JavaDoc），若注释位置非法，会实时标红并提示“Cannot resolve symbol”。
- 建议开启 Optimize imports on the fly 和 Show JavaDoc on mouse move（在 Settings → Editor → General → Other 中），提升文档编写体验。
总结：@param 不是通用注释标签，而是方法级语义标签。修复的关键不是修改代码逻辑，而是将 JavaDoc “归位”——从类上方移到对应方法上方。此举既消除 IDE 报错，也符合 JavaDoc 规范，确保生成的 API 文档准确可读。
Java免费学习笔记：立即使用
解锁 Java 大师之旅：从入门到精通的终极指南
