【Java开发300个实用技巧】223.API设计REST规范-CSDN博客

本文链接：https://blog.csdn.net/jrckkyy/article/details/147853584

在这里插入图片描述

API设计的艺术：如何用REST规范打造人见人爱的接口？掌握这六大核心法则，让你的接口既优雅又能打！

资源即一切：URI命名规范
动词归HTTP：方法使用法则
状态码会说话：响应设计技巧
版本管理：优雅演进的艺术
文档即契约：Swagger实战
安全防线：HTTPS+JWT最佳实践

嗨，你好呀，我是你的老朋友精通代码大仙。接下来我们一起学习Java开发中的300个实用技巧，震撼你的学习轨迹！

“接口不规范，同事两行泪”，这可不是段子！上周有个学员问我：“为什么我写的接口前端用着总骂娘？明明功能都实现了啊！” 看着他发来的混乱URI和随性的状态码，我仿佛看到了当年踩坑的自己。今天就让我们用REST规范打造让人一见倾心的API，让你的接口成为团队里的模范生！

1. 资源即一切：URI命名规范

点题：URI是资源的身份证，命名决定第一印象

痛点现场：

// 反面教材：动词满天飞
@GetMapping("/getUserList") 
@PostMapping("/createNewOrder")
@DeleteMapping("/removeProductById")

这种写法就像把地址写成"右转第三棵树下"，新人接手得拿地图才能看懂

正确姿势：

// 资源用名词，动词交给HTTP方法
@GetMapping("/users")         // 获取用户列表
@PostMapping("/orders")       // 创建新订单
@DeleteMapping("/products/{id}") // 删除指定商品

URI分层结构清晰可见：

/api
  /v1
    /users
      /{userId}
        /orders

小结：URI是资源定位器，不是方法说明书，记住"名词复数，层级分明"八字诀

2. 动词归HTTP：方法使用法则

点题：HTTP方法不是摆设，用错方法等于闯红灯

经典翻车现场：

@PostMapping("/updateUser")  // 用POST执行更新操作
@GetMapping("/deleteOrder")  // GET请求删数据，等着被CSRF攻击吧

正确操作：

@GetMapping("/users/{id}")     // 获取单个用户
@PostMapping("/users")         // 创建用户
@PutMapping("/users/{id}")     // 全量更新
@PatchMapping("/users/{id}")  // 部分更新
@DeleteMapping("/users/{id}")  // 删除用户

幂等性口诀：GET/HEAD/PUT/DELETE要安全，POST/PATCH操作要谨慎

小结：每个HTTP方法都有宪法地位，乱用就像把叉子当汤匙

3. 状态码会说话：响应设计技巧

点题：状态码是接口的表情包，乱用等于对牛弹琴

新手迷惑行为：

// 不管成功失败都返回200
return ResponseEntity.ok().body(new Result(500, "服务器开小差了"));

前端同事：“你这接口比女朋友还难猜！”

专业响应模板：

// 成功案例
@GetMapping("/users/{id}")
public ResponseEntity<User> getUser(@PathVariable Long id) {
    return userRepository.findById(id)
           .map(user -> ResponseEntity.ok(user))
           .orElse(ResponseEntity.notFound().build());
}

// 错误处理
@ExceptionHandler(MethodArgumentNotValidException.class)
public ResponseEntity<ErrorResponse> handleValidationException() {
    return ResponseEntity.status(HttpStatus.BAD_REQUEST)
           .body(new ErrorResponse("VALID_ERROR", "参数校验失败"));
}

常用状态码速记：

200 OK：常规成功
201 Created：创建成功
204 No Content：删除成功
400 Bad Request：客户端抽风
401 Unauthorized：需要登录
403 Forbidden：权限不足
404 Not Found：资源失踪
429 Too Many Requests：请求限流

小结：状态码是接口的摩斯密码，用对了沟通效率提升200%

4. 版本管理：优雅演进的艺术

点题：版本控制是接口的时光机，拒绝野蛮生长

血泪教训：

// 直接修改旧接口导致线上事故
@Deprecated
@GetMapping("/v1/users")  // 突然废弃旧版
public List<User> getUsersV1() {...}

优雅演进方案：

// 通过URI版本控制
@GetMapping("/v1/users")
public List<User> getUsersV1() {...}

@GetMapping("/v2/users")
public PagedUsers getUsersV2(@RequestParam int page, 
                            @RequestParam int size) {...}

// 请求头版本控制
@GetMapping(value = "/users", headers = "X-API-Version=2")
public PagedUsers getUsersV2(...) {...}

版本管理三原则：

最少3个版本共存
旧版本用@Deprecated标注
文档明确每个版本的退役时间

小结：版本管理就像接口的养老保险，现在规划将来不慌

5. 文档即契约：Swagger实战

点题：文档是接口的结婚证，拒绝口头协议

典型反面教材：

// 没有文档注解的接口
@PostMapping("/orders")
public Order createOrder(...) {...}

前端：“这个字段是干嘛的？要不要传？什么格式？”

Swagger武装到牙齿：

@Operation(summary = "创建订单", description = "需要登录权限")
@ApiResponses({
    @ApiResponse(responseCode = "201", description = "订单创建成功"),
    @ApiResponse(responseCode = "400", description = "参数校验失败")
})
@PostMapping("/orders")
public ResponseEntity<Order> createOrder(
    @Parameter(description = "订单创建请求体", required = true)
    @Valid @RequestBody OrderCreateRequest request) {
    //...
}

配置SwaggerUI：

@Bean
public OpenAPI springShopOpenAPI() {
    return new OpenAPI()
        .info(new Info().title("电商平台API")
        .version("v1.0.0")
        .contact(new Contact().name("大仙").url("https://blog.csdn.net/xxx")));
}

小结：Swagger是接口的自动翻译机，省下50%的沟通成本

6. 安全防线：HTTPS+JWT最佳实践

点题：安全是接口的防盗门，别等被黑才后悔

危险操作合集：

// 明文传输密码
@PostMapping("/login")
public void login(String username, String password) {...}

// 把token放在URL参数
@GetMapping("/profile?token=xxx")

安全组合拳：

// JWT认证流程
@PostMapping("/auth/login")
public ResponseEntity<AuthResponse> login(@RequestBody LoginRequest request) {
    // 验证账号密码
    String token = Jwts.builder()
        .setSubject(user.getUsername())
        .setExpiration(new Date(System.currentTimeMillis() + 3600000))
        .signWith(SignatureAlgorithm.HS512, secretKey)
        .compact();
    return ResponseEntity.ok(new AuthResponse(token));
}

// 接口安全配置
@Configuration
@EnableWebSecurity
public class SecurityConfig extends WebSecurityConfigurerAdapter {
    @Override
    protected void configure(HttpSecurity http) throws Exception {
        http.csrf().disable()
            .authorizeRequests()
            .antMatchers("/auth/**").permitAll()
            .anyRequest().authenticated()
            .and()
            .addFilter(new JwtAuthFilter(authenticationManager()));
    }
}