当前位置：首页 > 后端开发 > 正文

java怎么写外部接口

在Java中，常用Spring Boot框架写外部接口，先建Spring Boot项目，用 @RestController标控制器类， @RequestMapping定路径，方法参数接收请求数据，返回对象

核心概念解析

术语 定义 典型应用场景
RESTful API 基于HTTP协议的资源风格架构 Web服务、微服务通信
OpenAPI 开放接口描述规范（原Swagger） API文档标准化
DTO Data Transfer Object 前后端数据交互载体
Controller MVC模式中的控制层 请求路由与业务逻辑调度
Service 业务逻辑封装层 核心算法实现
Repository 数据持久化操作层 数据库CRUD操作

技术栈选型建议

主流框架对比表

框架 特点 适用场景
Spring Boot 约定优于配置，快速启动，生态完善 企业级应用首选
Quarkus 云原生优化，启动速度快，内存占用低 容器化/Serverless
Micronaut JVM热重载，低延迟 高性能要求场景
Vert.x 多语言支持，异步非阻塞 高并发实时系统

推荐方案：采用Spring Boot + MyBatis Plus组合，兼顾开发效率与灵活性，配合Lombok减少样板代码，Hutool工具包增强功能。

java怎么写外部接口 第1张

接口设计规范

URL路径设计原则

  • 复数名词：/api/users而非/api/user
  • 版本隔离：/v1/orders > /orders
  • 层级关系：/departments/{deptId}/employees
  • 动作语义：
    | HTTP Method | 操作类型 | 示例路径 |
    |————-|—————-|————————-|
    | GET | 查询资源 | /products |
    | POST | 创建资源 | /products |
    | PUT | 更新资源 | /products/{id} |
    | DELETE | 删除资源 | /products/{id} |
    | PATCH | 局部修改 | /products/{id} |

请求/响应规范

  • 请求头：Content-Type: application/json
  • 响应结构： 
    public class ApiResponse<T> {
  private int code;      // 业务状态码（非HTTP码）
  private String msg;    // 提示信息
  private T data;        // 实际数据
  private long timestamp;// 时间戳
}
  • 错误码体系：建立分级错误码机制（系统级/业务级/第三方异常）

完整实现步骤

项目初始化

通过Spring Initializr创建项目，添加以下依赖：

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
    <groupId>com.baomidou</groupId>
    <artifactId>mybatis-plus-boot-starter</artifactId>
    <version>3.5.3</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>

实体类与DTO设计

@Data
@TableName("tb_user")
public class UserEntity {
    @TableId(type = IdType.AUTO)
    private Long id;
    @TableField("user_name")
    private String userName;
    // getter/setter自动生成
}
@Data
public class UserDTO {
    @NotBlank(message = "用户名不能为空")
    private String userName;
    @Email(message = "邮箱格式错误")
    private String email;
}

控制器层实现

@RestController
@RequestMapping("/api/users")
@Validated // 启用参数校验
public class UserController {
    @Autowired
    private UserService userService;
    @GetMapping("/{id}")
    public ApiResponse<UserDTO> getUser(@PathVariable Long id) {
        UserEntity entity = userService.getById(id);
        return ApiResponse.success(convertToDTO(entity));
    }
    @PostMapping
    public ApiResponse<Void> createUser(@Valid @RequestBody UserDTO dto) {
        userService.createUser(dto);
        return ApiResponse.success();
    }
    private UserDTO convertToDTO(UserEntity entity) {
        // 使用MapStruct或手动转换
        UserDTO dto = new UserDTO();
        dto.setUserName(entity.getUserName());
        return dto;
    }
}

全局异常处理

@ControllerAdvice
public class GlobalExceptionHandler {
    @ExceptionHandler(MethodArgumentNotValidException.class)
    public ApiResponse<String> handleValidationException(MethodArgumentNotValidException e) {
        String errorMsg = e.getBindingResult().getAllErrors().stream()
                .map(DefaultMessageSourceResolvable::getDefaultMessage)
                .collect(Collectors.joining(";"));
        return ApiResponse.fail(400, errorMsg);
    }
}

Swagger文档配置

springfox:
  documentation:
    swagger-ui:
      enabled: true
      path: /swagger-ui.html
    paths: all # 扫描所有接口

关键优化点

性能优化策略

优化方向 实施方案 效果
缓存机制 Redis缓存热点数据 QPS提升5-10倍
异步处理 WebFlux响应式编程/CompletableFuture 降低线程阻塞时间
SQL优化 索引优化+分页查询（PageHelper） 复杂查询速度提升70%
GZIP压缩 开启HTTP压缩 网络传输量减少60%+

安全防护措施

  • 身份认证：JWT令牌+RBAC权限控制
  • 防重放攻击：RequestHeader中的If-Match/If-None-Match
  • 速率限制：令牌桶算法实现API限流
  • 敏感数据处理：AES加密+脱敏展示（如手机号中间四位号）

测试验证方法

Postman测试要点

  • 环境隔离：创建Dev/Test/Prod三个环境配置集
  • 自动化脚本：编写Collection Runner进行回归测试
  • 断言设置：同时验证HTTP状态码、响应体结构和业务数据

单元测试示例

@SpringBootTest
@AutoConfigureMockMvc
class UserControllerTest {
    @Autowired
    private MockMvc mockMvc;
    @Test
    void testCreateUser() throws Exception {
        mockMvc.perform(post("/api/users")
                .contentType(MediaType.APPLICATION_JSON)
                .content("{"userName":"test","email":"test@example.com"}"))
                .andExpect(status().isOk())
                .andExpect(jsonPath("$.code").value(200));
    }
}

常见问题FAQs

Q1: 如何解决前端跨域请求问题？

A：在Spring Boot中可通过两种方式解决：

java怎么写外部接口 第2张

  1. 全局配置（推荐）：在WebMvcConfig中添加： 
    @Configuration
public class WebConfig implements WebMvcConfigurer {
 @Override
 public void addCorsMappings(CorsRegistry registry) {
     registry.addMapping("/")
             .allowedOrigins("")
             .allowedMethods("GET", "POST", "PUT", "DELETE")
             .allowCredentials(true);
 }
}
  2. 注解方式：在特定控制器方法上添加@CrossOrigin注解，注意生产环境应限制允许的域名。

Q2: 如何统一处理接口返回格式？

A：通过ResponseBodyAdvice接口实现全局拦截器：

java怎么写外部接口 第3张

@RestControllerAdvice
public class GlobalResponseAdvice implements ResponseBodyAdvice<Object> {
    @Override
    public boolean supports(Class<? extends Object> clazz) {
        return true; // 对所有响应生效
    }
    @Override
    public Object beforeBodyWrite(Object body, MethodParameter methodParam, MediaType mediaType, Class<? extends Object> clazz, ServerHttpRequest request, ServerHttpResponse response) {
        if (body instanceof String) { // 处理字符串响应
            return ApiResponse.success(body);
        } else if (body instanceof ApiResponse) { // 已包装过的响应直接返回
            return body;
        } else { // 普通对象包装为标准响应
            return ApiResponse.success(body);
        }
Java
0

相关文章