getActiveUsers() {
return userDAO.findByStatus("active");
}
```
### `@throws` / `@exception` 异常说明 ###
```java
/**
* 文件上传处理
*
* @param file 上传的文件
* @throws FileNotFoundException 当文件不存在时抛出
* @throws FileSizeExceededException 当文件大小超过限制时抛出
* @throws IOException 当文件读写发生错误时抛出
*/
public void uploadFile(File file) throws FileNotFoundException,
FileSizeExceededException,
IOException {
if (!file.exists()) {
throw new FileNotFoundException("文件不存在: " + file.getName());
}
// 其他处理逻辑
}
/**
* 用户登录验证
*
* @param username 用户名
* @param password 密码
* @exception AuthenticationException 当用户名或密码错误时抛出
* @exception AccountLockedException 当账户被锁定时抛出
*/
public void login(String username, String password)
throws AuthenticationException, AccountLockedException {
// 登录逻辑
}
```
### `@see` 参考链接 ###
```java
/**
* 订单支付服务
*
* @see Order 订单实体类
* @see PaymentController#processPayment(Long) 支付处理方法
* @see 支付API文档
* @see "Java编程规范"
* @see #refund(Long) 退款方法
*/
public class PaymentService {
/**
* 执行支付
* @see PaymentGateway 支付网关接口
*/
public void processPayment(Order order) {
// 支付逻辑
}
/**
* 订单退款
*
* @see #processPayment(Order)
*/
public void refund(Long orderId) {
// 退款逻辑
}
}
```
### `@deprecated` 过时说明 ###
```java
public class OldClass {
/**
* @deprecated 这个字段已过时，请使用 {@link #newField} 替代。
* 将在下一个主要版本中移除。
*/
@Deprecated
private String oldField;
private String newField;
/**
* @deprecated 这个方法已过时，因为性能问题。
* 请使用 {@link #newMethod(String)} 替代。
*
* @param name 用户名
* @return 处理结果
*/
@Deprecated(since = "2.0", forRemoval = true)
public String oldMethod(String name) {
return "old result";
}
/**
* 新的处理方法
*/
public String newMethod(String name) {
return "new result";
}
}
```
### `{@code}` - 代码格式 ###
```java
/**
* 设置配置项
*
* 使用方法：
* {@code
* Config config = new Config();
* config.setProperty("key", "value");
* }
*
* 或者单行代码：{@code String name = "John";}
*
* @param key 配置键，格式为 {@code "section.name"}
* @param value 配置值
*/
public void setProperty(String key, String value) {
// 方法实现
}
```
### `{@link}` - 内部链接 ###
```java
/**
* 用户管理服务
*
* 相关方法：
* - {@link #createUser(User)}
* - {@link #updateUser(User)}
* - {@link #deleteUser(Long)}
*
* 相关类：
* - {@link User}
* - {@link UserDao}
*
* @see UserService
*/
public class UserManager {
/**
* 创建用户
*
* @param user 用户对象，参考 {@link User} 类定义
* @return 用户ID
* @see #updateUser(User)
*/
public Long createUser(User user) {
return 1L;
}
}
```
### `{@literal}` - 文本字面量 ###
```java
/**
* 特殊字符说明
*
* 在XML中需要使用 {@literal } 和 {@literal } 标签。
* 在正则表达式中使用 {@literal [a-z]+} 匹配小写字母。
*
* 比较操作：{@literal a < b && c > d}
*/
public class SpecialCharacters {
// 类实现
}
```
## Java注释中的HTML标签详解 ##
### `` - 段落标签 ###
```java
/**
* 用户服务类
*
*
这个类负责处理用户相关的所有业务逻辑。
*
* 包括用户注册、登录验证、信息修改等功能。
* 每个功能都经过严格测试，确保业务逻辑的正确性。
*
* 在使用时需要注意线程安全问题，建议配合Spring容器使用。
*/
public class UserService {
// 在Javadoc中，标签会自动在段落间创建空行，使文档更易读
}
```
### `
` - 换行标签 ###
```java
/**
* 地址验证工具
*
*
验证规则：
* 1. 地址不能为空
* 2. 地址长度不超过200字符
* 3. 必须包含省市区信息
* 4. 详细地址不能包含特殊字符
*
* 注意：此验证仅针对中国大陆地址，
* 国际地址需要使用其他验证规则。
*/
public class AddressValidator {
//
适合在同一个段落内创建列表式内容
}
```
### `` 和 `` - 粗体标签 ###
用途：强调重要文本
```java
/**
* 支付安全服务
*
* 重要提示：所有支付操作都必须记录审计日志。
*
* 安全警告：API密钥必须加密存储，
* 严禁在日志中输出敏感信息。
*
* 普通文本，关键操作需要双重验证，
* 高风险操作需要管理员审批。
*/
public class PaymentSecurityService {
// 和在视觉上效果相同，但语义上更强调重要性
}
```
### `` 和 `` - 斜体标签 ###
用途：表示技术术语、外来语或强调
```java
/**
* 科学计算工具
*
* 本类提供常用的科学计算功能：
*
* 欧拉公式：e^(iπ) + 1 = 0
* 勾股定理：a² + b² = c²
*
* 注意：浮点数计算可能存在精度问题，
* 大规模矩阵运算建议使用专业数学库。
*/
public class MathUtils {
// 通常用于技术术语，用于语义强调
}
```
### `` - 无序列表 ###
用途：创建项目符号列表
```java
/**
* 功能特性说明
*
* 主要功能：
*
* - 用户认证和授权
* - 数据加密存储
*
* - AES-256加密敏感数据
* - RSA加密传输数据
*
*
* - 审计日志记录
* - 性能监控和统计
*
*
* 技术特点：
*
* - 基于Spring Boot框架
* - 支持多数据源
* - 内置缓存机制
*
*/
public class SystemFeatures {
// 创建带项目符号的列表，适合列举特性、功能点等
}
```
### `` - 有序列表 ###
用途：创建带编号的步骤列表
```java
/**
* 安装配置指南
*
* 安装步骤：
*
* - 下载安装包
* - 解压到目标目录
* - 修改配置文件
*
* - 配置数据库连接
* - 设置管理员账号
* - 配置日志路径
*
*
* - 启动服务
* - 验证安装结果
*
*
* 启动顺序：
*
* - 数据库服务
* - 缓存服务
* - 应用服务
* - 监控服务
*
*/
public class InstallationGuide {
// 创建带数字编号的列表，适合步骤、流程说明
}
```
## 总结 ##
编写文档注释并非单纯的体力劳动，它是一种设计活动。当你被迫用自然语言清晰地描述一个方法时，往往会发现代码逻辑本身的模糊或设计上的缺陷。高质量的 Javadoc 是代码重构的催化剂。
作为 Java 后端高级开发，当我们从单纯关注“代码怎么跑”转变为关注“代码怎么读”时，我们就跨越了从工匠到大师的门槛。希望这篇博文能成为你团队中的“文档圣经”，不仅提升代码库的健康度，更在技术社区中树立你作为 uncompromising engineer（不妥协的工程师）的专业形象。让我们一起，用注释点亮代码的黑暗角落