service-example.md 7.8 KB
Service 代码注释示例
场景
为 Service 接口和实现类添加完整的 JavaDoc 注释。
Service 接口示例
原始代码
package com.example.service;
import com.example.dto.UserDTO;
import java.util.List;
public interface UserService {
UserDTO createUser(UserCreateRequest request);
UserDTO findById(Long id);
List<UserDTO> findAll();
UserDTO updateUser(Long id, UserUpdateRequest request);
void deleteById(Long id);
}
添加注释后的代码
package com.example.service;
import com.example.dto.UserDTO;
import java.util.List;
/**
* 用户服务接口
*
* <p>定义用户相关的业务逻辑接口，包括用户的增删改查操作。
* 本接口遵循领域驱动设计（DDD）原则，封装用户领域的核心业务逻辑。
*
* <p>主要职责：
* <ul>
* <li>用户创建和注册</li>
* <li>用户信息查询</li>
* <li>用户信息更新</li>
* <li>用户删除</li>
* </ul>
*
* @author System
* @since 1.0.0
*/
public interface UserService {
/**
* 创建新用户
*
* <p>根据用户创建请求创建新用户，包括数据验证、密码加密等处理。
*
* @param request 用户创建请求对象
* @return 创建成功的用户信息 DTO
* @throws IllegalArgumentException 当请求参数不合法时抛出
* @throws BusinessException 当用户名或邮箱已存在时抛出
*/
UserDTO createUser(UserCreateRequest request);
/**
* 根据 ID 查询用户
*
* <p>根据用户 ID 查询用户详细信息，如果用户不存在则抛出异常。
*
* @param id 用户唯一标识符
* @return 用户信息 DTO
* @throws ResourceNotFoundException 当用户不存在时抛出
*/
UserDTO findById(Long id);
/**
* 查询所有用户
*
* <p>查询系统中所有用户的信息列表。
*
* @return 用户信息 DTO 列表
*/
List<UserDTO> findAll();
/**
* 更新用户信息
*
* <p>根据用户 ID 和更新请求，更新用户的指定字段信息。
*
* @param id 用户唯一标识符
* @param request 用户更新请求对象
* @return 更新后的用户信息 DTO
* @throws ResourceNotFoundException 当用户不存在时抛出
* @throws IllegalArgumentException 当更新参数不合法时抛出
*/
UserDTO updateUser(Long id, UserUpdateRequest request);
/**
* 根据 ID 删除用户
*
* <p>根据用户 ID 删除指定用户，删除操作会级联删除用户相关的数据。
*
* @param id 用户唯一标识符
* @throws ResourceNotFoundException 当用户不存在时抛出
*/
void deleteById(Long id);
}
ServiceImpl 实现类示例
原始代码
package com.example.service.impl;
import com.example.service.UserService;
import com.example.dto.UserDTO;
import com.example.mapper.UserMapper;
import org.springframework.stereotype.Service;
import java.util.List;
@Service
public class UserServiceImpl implements UserService {
private final UserMapper userMapper;
public UserServiceImpl(UserMapper userMapper) {
this.userMapper = userMapper;
}
@Override
public UserDTO createUser(UserCreateRequest request) {
// 验证用户名是否已存在
if (userMapper.existsByUsername(request.getUsername())) {
throw new BusinessException("用户名已存在");
}
// 创建用户实体
User user = new User();
user.setUsername(request.getUsername());
user.setEmail(request.getEmail());
user.setPassword(passwordEncoder.encode(request.getPassword()));
// 保存到数据库
userMapper.insert(user);
// 转换为 DTO 返回
return convertToDTO(user);
}
@Override
public UserDTO findById(Long id) {
User user = userMapper.selectById(id);
if (user == null) {
throw new ResourceNotFoundException("用户不存在");
}
return convertToDTO(user);
}
// ... 其他方法
}
添加注释后的代码
package com.example.service.impl;
import com.example.service.UserService;
import com.example.dto.UserDTO;
import com.example.mapper.UserMapper;
import org.springframework.stereotype.Service;
import java.util.List;
/**
* 用户服务实现类
*
* <p>实现 {@link UserService} 接口，提供用户相关的业务逻辑实现。
* 本类负责处理用户创建、查询、更新、删除等核心业务操作。
*
* <p>主要功能：
* <ul>
* <li>用户创建：包括数据验证、密码加密、重复性检查</li>
* <li>用户查询：支持按 ID 查询和全量查询</li>
* <li>用户更新：支持部分字段更新</li>
* <li>用户删除：级联删除相关数据</li>
* </ul>
*
* @author System
* @since 1.0.0
*/
@Service
public class UserServiceImpl implements UserService {
/**
* 用户数据访问对象
*
* <p>用于执行用户相关的数据库操作
*/
private final UserMapper userMapper;
/**
* 密码编码器
*
* <p>用于对用户密码进行加密处理
*/
private final PasswordEncoder passwordEncoder;
/**
* 构造函数
*
* @param userMapper 用户数据访问对象，由 Spring 容器注入
* @param passwordEncoder 密码编码器，由 Spring 容器注入
*/
public UserServiceImpl(UserMapper userMapper, PasswordEncoder passwordEncoder) {
this.userMapper = userMapper;
this.passwordEncoder = passwordEncoder;
}
/**
* 创建新用户
*
* <p>实现用户创建的业务逻辑，包括：
* <ol>
* <li>验证用户名是否已存在</li>
* <li>验证邮箱是否已存在</li>
* <li>对密码进行加密处理</li>
* <li>创建用户实体并保存到数据库</li>
* <li>转换为 DTO 返回</li>
* </ol>
*
* @param request 用户创建请求对象，包含用户名、邮箱、密码等信息
* @return 创建成功的用户信息 DTO
* @throws IllegalArgumentException 当请求参数不合法时抛出
* @throws BusinessException 当用户名或邮箱已存在时抛出
*/
@Override
public UserDTO createUser(UserCreateRequest request) {
// 验证用户名是否已存在
if (userMapper.existsByUsername(request.getUsername())) {
throw new BusinessException("用户名已存在");
}
// 创建用户实体
User user = new User();
user.setUsername(request.getUsername());
user.setEmail(request.getEmail());
user.setPassword(passwordEncoder.encode(request.getPassword()));
// 保存到数据库
userMapper.insert(user);
// 转换为 DTO 返回
return convertToDTO(user);
}
/**
* 根据 ID 查询用户
*
* <p>根据用户 ID 从数据库查询用户信息，如果用户不存在则抛出异常。
*
* @param id 用户唯一标识符
* @return 用户信息 DTO
* @throws ResourceNotFoundException 当用户不存在时抛出
*/
@Override
public UserDTO findById(Long id) {
User user = userMapper.selectById(id);
if (user == null) {
throw new ResourceNotFoundException("用户不存在");
}
return convertToDTO(user);
}
// ... 其他方法
}
注释要点
接口注释：
- 说明接口的职责和设计原则
- 列出主要功能点
- 每个方法都要有详细的 JavaDoc
实现类注释：
- 说明实现类的职责
- 描述实现的主要功能
- 字段注释说明依赖关系
- 方法注释详细说明实现逻辑