【java接口实现】一个简单接口实现模板

】

1. 概述

接口开发过程中的规范和最佳实践，涵盖 Controller、Service、Mapper、实体类和响应类等各层组件的设计。

2. 项目架构

2.1 分层架构设计

top.continew.admin.system/
├── controller/           # 控制器层 - 处理HTTP请求和响应
├── service/              # 业务逻辑层
│   ├── impl/            # 业务逻辑实现类
│   └── *.java           # 业务逻辑接口
├── mapper/              # 数据访问层
├── model/               # 数据模型层
│   ├── entity/          # 数据库实体类
│   ├── resp/            # 响应数据模型
│   ├── req/             # 请求数据模型
│   └── query/           # 查询条件模型
└── config/              # 配置类

2.2 数据流向

HTTP Request → Controller → Service → ServiceImpl → Mapper → Database↓
HTTP Response ← Controller ← Service ← ServiceImpl ← Mapper ← Database

3. 命名规范

3.1 文件命名规则

组件类型	命名格式	示例
Controller	[模块名]Controller.java	UserController.java
Service接口	[模块名]Service.java	UserService.java
Service实现	[模块名]ServiceImpl.java	UserServiceImpl.java
Mapper接口	[模块名]Mapper.java	UserMapper.java
实体类	[模块名]DO.java	UserDO.java
响应类	[模块名]Resp.java	UserResp.java
请求类	[模块名]Req.java	UserReq.java
查询类	[模块名]Query.java	UserQuery.java

3.2 包名规范

// 控制器层
top.continew.admin.模块名称.controller// 服务层
top.continew.admin.模块名称.service
top.continew.admin.模块名称.service.impl// 数据访问层
top.continew.admin.模块名称.mapper// 数据模型层
top.continew.admin.模块名称.model.entity
top.continew.admin.模块名称.model.resp
top.continew.admin.模块名称.model.req
top.continew.admin.模块名称.model.query

4. 各层组件规范

4.1 Controller 层规范

4.1.1 基本结构

位置: `/controller/TestController.java**

package top.continew.admin.system.controller;import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.enums.ParameterIn;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RestController;import lombok.RequiredArgsConstructor;
import top.continew.admin.system.model.resp.TestResp;
import top.continew.admin.system.service.TestService;
import top.continew.starter.extension.crud.annotation.CrudRequestMapping;import java.util.List;/*** 测试控制器** @author Charles7c* @since 2023/1/22 17:55*/
@Tag(name = "测试 API")
@RestController
@CrudRequestMapping(value = "/system/test")
@RequiredArgsConstructor
public class TestController {private final TestService testService;@Operation(summary = "测试", description = "测试接口描述")@Parameter(name = "id", description = "部门 ID", example = "1", in = ParameterIn.PATH)@GetMapping("/cs/{id}")public List<TestResp> test(@PathVariable Long id) {return testService.getTestData(id);}
}

4.1.2 注解说明

• @Tag: 定义API分组
• @RestController: 声明RESTful控制器
• @CrudRequestMapping: CRUD路由映射
• @RequiredArgsConstructor: Lombok构造器注入
• @Operation: Swagger接口描述
• @Parameter: Swagger参数描述

4.2 Service 层规范

4.2.1 Service接口

位置: `/service/DictService.java**

package top.continew.admin.system.service;import top.continew.admin.common.base.service.BaseService;
import top.continew.admin.system.model.entity.DictDO;
import top.continew.admin.system.model.query.DictQuery;
import top.continew.admin.system.model.req.DictReq;
import top.continew.admin.system.model.resp.DictResp;
import top.continew.starter.data.service.IService;
import top.continew.starter.extension.crud.model.resp.LabelValueResp;import java.util.List;/*** 字典业务接口** @author Charles7c* @since 2023/9/11 21:29*/
public interface DictService extends BaseService<DictResp, DictResp, DictQuery, DictReq>, IService<DictDO> {/*** 查询枚举字典** @return 枚举字典列表*/List<LabelValueResp> listEnumDict();
}

4.2.2 Service实现类

位置: `/service/impl/TestServiceImpl.java**

package top.continew.admin.system.service.impl;import cn.hutool.core.collection.CollUtil;
import com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper;
import lombok.RequiredArgsConstructor;
import org.springframework.stereotype.Service;
import top.continew.admin.system.mapper.TestMapper;
import top.continew.admin.system.model.entity.TestDO;
import top.continew.admin.system.model.resp.TestResp;
import top.continew.admin.system.service.TestService;import java.util.ArrayList;
import java.util.List;
import java.util.stream.Collectors;/*** 测试业务实现** @author Charles7c* @since 2023/1/22 17:55*/
@Service
@RequiredArgsConstructor
public class TestServiceImpl implements TestService {private final TestMapper testMapper;@Overridepublic List<TestResp> getTestData(Long id) {// 构建查询条件LambdaQueryWrapper<TestDO> queryWrapper = new LambdaQueryWrapper<>();if (id != null) {queryWrapper.eq(TestDO::getId, id);}// 执行数据库查询List<TestDO> testDOList = testMapper.selectList(queryWrapper);// 空值处理if (CollUtil.isEmpty(testDOList)) {return new ArrayList<>();}// 数据转换：DO → Respreturn testDOList.stream().map(this::convertToResp).collect(Collectors.toList());}/*** 将实体对象转换为响应对象*/private TestResp convertToResp(TestDO testDO) {TestResp testResp = new TestResp();testResp.setId(testDO.getId());testResp.setName(testDO.getName());// 设置业务数据List<Long> list = new ArrayList<>();list.add(1L);list.add(3L);testResp.setList(list);return testResp;}
}

4.3 Mapper 层规范

位置: `/mapper/TestMapper.java**

package top.continew.admin.system.mapper;import org.apache.ibatis.annotations.Mapper;
import com.baomidou.mybatisplus.core.mapper.BaseMapper;
import top.continew.admin.system.model.entity.TestDO;/*** 测试Mapper** @author Charles7c* @since 2024/1/1*/
@Mapper
public interface TestMapper extends BaseMapper<TestDO> {
}

4.4 数据模型规范

4.4.1 实体类 (Entity)

位置: `/model/entity/TestDO.java**

package top.continew.admin.system.model.entity;import com.baomidou.mybatisplus.annotation.TableName;
import lombok.Data;import java.io.Serial;/*** 测试实体** @author Charles7c* @since 2024/1/1*/
@Data
@TableName("test")
public class TestDO {@Serialprivate static final long serialVersionUID = 1L;/*** ID*/private Long id;/*** 名称*/private String name;
}

4.4.2 响应类 (Response)

位置: `/model/resp/TestResp.java**

package top.continew.admin.system.model.resp;import io.swagger.v3.oas.annotations.media.Schema;
import lombok.Data;import java.util.List;/*** 测试响应信息** @author Charles7c* @since 2023/1/22 17:55*/
@Data
@Schema(description = "测试响应信息")
public class TestResp {@Schema(description = "ID", example = "1")private Long id;@Schema(description = "部门名称", example = "技术部")private String name;@Schema(description = "列表数据")private List<Long> list;
}

5. 开发最佳实践

5.1 代码规范

1. 分层清晰: 严格遵循Controller → Service → Mapper的调用顺序
2. 依赖注入: 使用构造器注入，避免字段注入
3. 异常处理: 在Service层处理业务异常，Controller层处理系统异常
4. 数据转换: 在Service层完成DO到Resp的转换
5. 文档注释: 所有公开方法必须添加Swagger注解和JavaDoc

5.2 接口设计原则

1. RESTful风格: 使用合适的HTTP方法和状态码
2. 统一响应: 保持响应数据结构的一致性
3. 参数校验: 在Controller层进行参数校验
4. 分页查询: 查询列表接口必须支持分页
5. 版本管理: 接口路径包含版本信息

5.3 性能优化建议

1. 数据库查询: 使用MyBatis-Plus的Lambda查询避免SQL注入
2. 集合操作: 使用Stream API进行数据转换和处理
3. 空值处理: 使用Hutool等工具类简化空值判断
4. 资源释放: 确保数据库连接等资源的正确释放

6. 常用工具类

6.1 集合工具

import cn.hutool.core.collection.CollUtil;// 集合判空
if (CollUtil.isEmpty(list)) {return new ArrayList<>();
}

6.2 条件构造器

import com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper;LambdaQueryWrapper<TestDO> queryWrapper = new LambdaQueryWrapper<>();
queryWrapper.eq(TestDO::getId, id);

6.3 Stream API

// 数据转换
list.stream().map(this::convertToResp).collect(Collectors.toList());

---