HTTP协议基础：请求方法、状态码与头部详解

// 用户管理API
@RestController
@RequestMapping("/api/users")
public class UserController {

    // GET /api/users - 查询所有用户
    @GetMapping
    public List<User> listUsers() {
        return userService.findAll();
    }

    // GET /api/users/123 - 查询单个用户
    @GetMapping("/{id}")
    public User getUser(@PathVariable Long id) {
        return userService.findById(id);
    }

    // POST /api/users - 创建用户
    @PostMapping
    public User createUser(@RequestBody User user) {
        return userService.create(user);
    }

    // PUT /api/users/123 - 完整更新用户
    @PutMapping("/{id}")
    public User updateUser(@PathVariable Long id, @RequestBody User user) {
        return userService.update(id, user);
    }

    // PATCH /api/users/123 - 部分更新用户
    @PatchMapping("/{id}")
    public User patchUser(@PathVariable Long id, @RequestBody Map<String, Object> updates) {
        return userService.patch(id, updates);
    }

    // DELETE /api/users/123 - 删除用户
    @DeleteMapping("/{id}")
    public void deleteUser(@PathVariable Long id) {
        userService.delete(id);
    }
}

HTTP/1.1 200 OK
Content-Type: application/json

{"id": 123, "name": "张三"}

HTTP/1.1 201 Created
Location: /api/users/123

{"id": 123, "name": "张三"}

HTTP/1.1 204 No Content

# 删除成功，无返回内容

# 客户端请求
GET /api/users/123
If-None-Match: "abc123"

# 服务器响应（资源未改变）
HTTP/1.1 304 Not Modified
ETag: "abc123"

# 客户端使用缓存

// Feign客户端添加请求头
@FeignClient(name = "user-service")
public interface UserClient {

    @GetMapping("/api/users/{id}")
    User getUser(@PathVariable Long id,
                 @RequestHeader("Authorization") String token,
                 @RequestHeader("X-Request-Id") String requestId);
}

// 全局请求拦截器
@Component
public class FeignRequestInterceptor implements RequestInterceptor {
    @Override
    public void apply(RequestTemplate template) {
        // 添加链路追踪ID
        template.header("X-Trace-Id", MDC.get("traceId"));

        // 添加租户ID（多租户场景）
        template.header("X-Tenant-Id", TenantContext.getTenantId());

        // 添加认证Token
        template.header("Authorization", "Bearer " + getToken());
    }
}

// 方式1：在Controller中设置
@GetMapping("/api/users/{id}")
public ResponseEntity<User> getUser(@PathVariable Long id) {
    User user = userService.findById(id);

    return ResponseEntity.ok()
        .header("X-Custom-Header", "custom-value")
        .eTag("\"" + user.getVersion() + "\"")  // ETag
        .cacheControl(CacheControl.maxAge(1, TimeUnit.HOURS))  // 缓存1小时
        .body(user);
}

// 方式2：全局响应拦截器
@Component
public class ResponseHeaderInterceptor implements HandlerInterceptor {
    @Override
    public void postHandle(HttpServletRequest request,
                          HttpServletResponse response,
                          Object handler,
                          ModelAndView modelAndView) {
        // 添加安全响应头
        response.setHeader("X-Content-Type-Options", "nosniff");
        response.setHeader("X-Frame-Options", "DENY");
        response.setHeader("X-XSS-Protection", "1; mode=block");
    }
}

# application.yml
spring:
  session:
    store-type: redis
  redis:
    host: localhost
    port: 6379

// Spring Session自动管理
@RestController
public class AuthController {

    @PostMapping("/login")
    public void login(HttpSession session, @RequestBody LoginRequest req) {
        User user = authService.authenticate(req.getUsername(), req.getPassword());
        session.setAttribute("user", user);  // 存入Redis
    }

    @GetMapping("/profile")
    public User profile(HttpSession session) {
        return (User) session.getAttribute("user");  // 从Redis读取
    }
}

// 无状态认证，不需要Session
@PostMapping("/login")
public LoginResponse login(@RequestBody LoginRequest req) {
    User user = authService.authenticate(req.getUsername(), req.getPassword());

    // 生成JWT Token
    String token = jwtUtil.generateToken(user);

    return new LoginResponse(token);
}

@GetMapping("/profile")
public User profile(@RequestHeader("Authorization") String authHeader) {
    String token = authHeader.substring(7);  // 去掉 "Bearer "
    User user = jwtUtil.parseToken(token);
    return user;
}

@PostMapping("/upload")
public UploadResponse uploadFile(@RequestParam("file") MultipartFile file) {
    // Content-Type: multipart/form-data; boundary=----WebKitFormBoundary

    String filename = file.getOriginalFilename();
    long size = file.getSize();
    String contentType = file.getContentType();

    // 保存文件
    String path = storageService.save(file);

    return new UploadResponse(path, filename, size);
}

// Spring Cloud Gateway
@Component
public class AuthFilter implements GlobalFilter, Ordered {

    @Override
    public Mono<Void> filter(ServerWebExchange exchange, GatewayFilterChain chain) {
        ServerHttpRequest request = exchange.getRequest();

        // 1. 获取Token
        String token = request.getHeaders().getFirst("Authorization");
        if (token == null || !token.startsWith("Bearer ")) {
            return unauthorized(exchange, "缺少认证Token");
        }

        // 2. 验证Token
        try {
            JwtClaims claims = jwtUtil.parseToken(token.substring(7));

            // 3. 传递用户信息到下游服务
            ServerHttpRequest mutatedRequest = request.mutate()
                .header("X-User-Id", claims.getUserId())
                .header("X-Username", claims.getUsername())
                .build();

            return chain.filter(exchange.mutate().request(mutatedRequest).build());

        } catch (Exception e) {
            return unauthorized(exchange, "Token无效");
        }
    }

    private Mono<Void> unauthorized(ServerWebExchange exchange, String message) {
        ServerHttpResponse response = exchange.getResponse();
        response.setStatusCode(HttpStatus.UNAUTHORIZED);
        response.getHeaders().set("Content-Type", "application/json");

        String body = "{\"error\": \"" + message + "\"}";
        DataBuffer buffer = response.bufferFactory().wrap(body.getBytes());

        return response.writeWith(Mono.just(buffer));
    }

    @Override
    public int getOrder() {
        return -100;  // 高优先级
    }
}

// 订单服务调用用户服务
@Service
public class OrderService {

    @Autowired
    private RestTemplate restTemplate;

    public Order createOrder(CreateOrderRequest request) {
        // 1. 获取当前用户信息（从请求上下文）
        String userId = SecurityContextHolder.getContext().getAuthentication().getName();

        // 2. 调用用户服务
        HttpHeaders headers = new HttpHeaders();
        headers.set("Authorization", "Bearer " + getToken());
        headers.set("X-Request-Id", UUID.randomUUID().toString());
        headers.set("X-Trace-Id", MDC.get("traceId"));

        HttpEntity<Void> entity = new HttpEntity<>(headers);

        User user = restTemplate.exchange(
            "http://user-service/api/users/" + userId,
            HttpMethod.GET,
            entity,
            User.class
        ).getBody();

        // 3. 创建订单
        Order order = new Order();
        order.setUserId(user.getId());
        order.setUsername(user.getName());
        // ...

        return orderRepository.save(order);
    }
}

@RestControllerAdvice
public class GlobalExceptionHandler {

    // 业务异常 → 400 Bad Request
    @ExceptionHandler(BusinessException.class)
    public ResponseEntity<ErrorResponse> handleBusinessException(BusinessException e) {
        return ResponseEntity
            .badRequest()
            .body(new ErrorResponse(e.getCode(), e.getMessage()));
    }

    // 未认证 → 401 Unauthorized
    @ExceptionHandler(AuthenticationException.class)
    public ResponseEntity<ErrorResponse> handleAuthException(AuthenticationException e) {
        return ResponseEntity
            .status(HttpStatus.UNAUTHORIZED)
            .body(new ErrorResponse("AUTH_FAILED", "认证失败"));
    }

    // 无权限 → 403 Forbidden
    @ExceptionHandler(AccessDeniedException.class)
    public ResponseEntity<ErrorResponse> handleAccessDenied(AccessDeniedException e) {
        return ResponseEntity
            .status(HttpStatus.FORBIDDEN)
            .body(new ErrorResponse("ACCESS_DENIED", "权限不足"));
    }

    // 资源不存在 → 404 Not Found
    @ExceptionHandler(ResourceNotFoundException.class)
    public ResponseEntity<ErrorResponse> handleNotFound(ResourceNotFoundException e) {
        return ResponseEntity
            .status(HttpStatus.NOT_FOUND)
            .body(new ErrorResponse("NOT_FOUND", e.getMessage()));
    }

    // 服务异常 → 500 Internal Server Error
    @ExceptionHandler(Exception.class)
    public ResponseEntity<ErrorResponse> handleException(Exception e) {
        log.error("服务异常", e);
        return ResponseEntity
            .status(HttpStatus.INTERNAL_SERVER_ERROR)
            .body(new ErrorResponse("INTERNAL_ERROR", "服务内部错误"));
    }
}