API设计最佳实践——RESTful接口规范

{
    "code": 0,
    "message": "success",
    "data": {
        "orderId": "ORD202402040001",
        "status": "PENDING",
        "totalAmount": 199.99,
        "currency": "USD"
    },
    "timestamp": 1707033600000,
    "traceId": "a1b2c3d4e5f6"
}

{
    "code": 0,
    "message": "success",
    "data": {
        "list": [
            {"orderId": "ORD001", "status": "PENDING"},
            {"orderId": "ORD002", "status": "SHIPPED"}
        ],
        "pagination": {
            "page": 1,
            "size": 20,
            "total": 156,
            "totalPages": 8
        }
    },
    "timestamp": 1707033600000,
    "traceId": "a1b2c3d4e5f6"
}

{
    "code": 40001,
    "message": "库存不足",
    "data": null,
    "timestamp": 1707033600000,
    "traceId": "a1b2c3d4e5f6",
    "errors": [
        {
            "field": "quantity",
            "message": "SKU001库存不足，当前可用: 5，请求数量: 10"
        }
    ]
}

/**
 * 统一响应结构
 */
@Data
public class ApiResponse<T> {
    private Integer code;
    private String message;
    private T data;
    private Long timestamp;
    private String traceId;
    private List<FieldError> errors;

    public static <T> ApiResponse<T> success(T data) {
        ApiResponse<T> response = new ApiResponse<>();
        response.setCode(0);
        response.setMessage("success");
        response.setData(data);
        response.setTimestamp(System.currentTimeMillis());
        response.setTraceId(TraceContext.getTraceId());
        return response;
    }

    public static <T> ApiResponse<T> error(Integer code, String message) {
        ApiResponse<T> response = new ApiResponse<>();
        response.setCode(code);
        response.setMessage(message);
        response.setTimestamp(System.currentTimeMillis());
        response.setTraceId(TraceContext.getTraceId());
        return response;
    }

    public static <T> ApiResponse<T> error(ErrorCode errorCode) {
        return error(errorCode.getCode(), errorCode.getMessage());
    }
}

/**
 * 分页响应
 */
@Data
public class PageResponse<T> {
    private List<T> list;
    private Pagination pagination;

    @Data
    public static class Pagination {
        private Integer page;
        private Integer size;
        private Long total;
        private Integer totalPages;
    }

    public static <T> PageResponse<T> of(Page<T> page) {
        PageResponse<T> response = new PageResponse<>();
        response.setList(page.getContent());

        Pagination pagination = new Pagination();
        pagination.setPage(page.getNumber() + 1);
        pagination.setSize(page.getSize());
        pagination.setTotal(page.getTotalElements());
        pagination.setTotalPages(page.getTotalPages());
        response.setPagination(pagination);

        return response;
    }
}

### 2.2 错误码设计

**错误码分层设计**：

@Data
public class PageRequest {
    @Min(1)
    private Integer page = 1;

    @Min(1)
    @Max(100)
    private Integer size = 20;

    private String sort = "createdAt";

    @Pattern(regexp = "^(asc|desc)$")
    private String order = "desc";

    public Pageable toPageable() {
        Sort.Direction direction = "asc".equalsIgnoreCase(order)
            ? Sort.Direction.ASC : Sort.Direction.DESC;
        return org.springframework.data.domain.PageRequest.of(
            page - 1, size, Sort.by(direction, sort)
        );
    }
}

@Data
public class CreateOrderRequest {

    @NotBlank(message = "渠道不能为空")
    @Size(max = 50, message = "渠道长度不能超过50")
    private String channel;

    @NotBlank(message = "客户ID不能为空")
    private String customerId;

    @NotEmpty(message = "订单明细不能为空")
    @Size(max = 100, message = "订单明细不能超过100条")
    @Valid
    private List<OrderItemRequest> items;

    @NotNull(message = "收货地址不能为空")
    @Valid
    private AddressRequest shippingAddress;

    @DecimalMin(value = "0.01", message = "订单金额必须大于0")
    @DecimalMax(value = "999999.99", message = "订单金额不能超过999999.99")
    private BigDecimal totalAmount;

    @Pattern(regexp = "^[A-Z]{3}$", message = "币种格式错误")
    private String currency = "USD";
}

@Data
public class OrderItemRequest {

    @NotBlank(message = "SKU不能为空")
    private String skuId;

    @NotNull(message = "数量不能为空")
    @Min(value = 1, message = "数量必须大于0")
    @Max(value = 9999, message = "数量不能超过9999")
    private Integer quantity;

    @DecimalMin(value = "0.01", message = "单价必须大于0")
    private BigDecimal unitPrice;
}

@RestControllerAdvice
public class GlobalExceptionHandler {

    /**
     * 参数校验异常
     */
    @ExceptionHandler(MethodArgumentNotValidException.class)
    @ResponseStatus(HttpStatus.BAD_REQUEST)
    public ApiResponse<Void> handleValidationException(MethodArgumentNotValidException e) {
        List<FieldError> errors = e.getBindingResult().getFieldErrors().stream()
            .map(error -> new FieldError(error.getField(), error.getDefaultMessage()))
            .collect(Collectors.toList());

        ApiResponse<Void> response = ApiResponse.error(ErrorCode.PARAM_ERROR);
        response.setErrors(errors);
        return response;
    }

    /**
     * 业务异常
     */
    @ExceptionHandler(BusinessException.class)
    @ResponseStatus(HttpStatus.UNPROCESSABLE_ENTITY)
    public ApiResponse<Void> handleBusinessException(BusinessException e) {
        return ApiResponse.error(e.getCode(), e.getMessage());
    }

    /**
     * 资源不存在
     */
    @ExceptionHandler(ResourceNotFoundException.class)
    @ResponseStatus(HttpStatus.NOT_FOUND)
    public ApiResponse<Void> handleNotFoundException(ResourceNotFoundException e) {
        return ApiResponse.error(ErrorCode.NOT_FOUND);
    }

    /**
     * 系统异常
     */
    @ExceptionHandler(Exception.class)
    @ResponseStatus(HttpStatus.INTERNAL_SERVER_ERROR)
    public ApiResponse<Void> handleException(Exception e) {
        log.error("系统异常", e);
        return ApiResponse.error(ErrorCode.SYSTEM_ERROR);
    }
}

/**
 * API版本管理
 */
public class ApiVersionPolicy {

    // 版本状态
    public enum VersionStatus {
        CURRENT,    // 当前版本
        DEPRECATED, // 已废弃（仍可用）
        RETIRED     // 已下线
    }

    // 版本信息
    public static final Map<String, VersionInfo> VERSIONS = Map.of(
        "v1", new VersionInfo("v1", VersionStatus.DEPRECATED,
            LocalDate.of(2024, 1, 1),  // 发布日期
            LocalDate.of(2024, 7, 1)), // 下线日期
        "v2", new VersionInfo("v2", VersionStatus.CURRENT,
            LocalDate.of(2024, 4, 1),
            null)
    );
}

@Component
public class DeprecationInterceptor implements HandlerInterceptor {

    @Override
    public void postHandle(HttpServletRequest request, HttpServletResponse response,
                          Object handler, ModelAndView modelAndView) {
        String version = extractVersion(request.getRequestURI());
        VersionInfo info = ApiVersionPolicy.VERSIONS.get(version);

        if (info != null && info.getStatus() == VersionStatus.DEPRECATED) {
            response.setHeader("Deprecation", "true");
            response.setHeader("Sunset", info.getRetireDate().toString());
            response.setHeader("Link", "</api/v2>; rel=\"successor-version\"");
        }
    }
}

// v1 响应
{
    "orderId": "ORD001",
    "status": "PENDING"
}

// v2 响应（兼容v1）
{
    "orderId": "ORD001",
    "status": "PENDING",
    "statusCode": 10,        // 新增字段
    "statusName": "待处理"   // 新增字段
}

// 使用@JsonInclude避免null字段
@Data
@JsonInclude(JsonInclude.Include.NON_NULL)
public class OrderResponse {
    private String orderId;
    private String status;
    private Integer statusCode;  // v2新增
    private String statusName;   // v2新增
}

/**
 * API签名工具
 */
public class ApiSignatureUtil {

    private static final long TIMESTAMP_TOLERANCE = 5 * 60 * 1000; // 5分钟

    /**
     * 生成签名
     */
    public static String sign(String timestamp, String nonce,
                             String apiKey, String body, String secret) {
        String content = timestamp + nonce + apiKey + body + secret;
        return DigestUtils.sha256Hex(content);
    }

    /**
     * 验证签名
     */
    public static boolean verify(SignatureParams params, String secret) {
        // 1. 验证时间戳（防重放攻击）
        long ts = Long.parseLong(params.getTimestamp());
        long now = System.currentTimeMillis();
        if (Math.abs(now - ts) > TIMESTAMP_TOLERANCE) {
            throw new AuthenticationException("时间戳已过期");
        }

        // 2. 验证nonce（防重放攻击）
        String nonceKey = "nonce:" + params.getNonce();
        if (redisTemplate.hasKey(nonceKey)) {
            throw new AuthenticationException("请求已处理");
        }
        redisTemplate.opsForValue().set(nonceKey, "1", 10, TimeUnit.MINUTES);

        // 3. 验证签名
        String expected = sign(params.getTimestamp(), params.getNonce(),
            params.getApiKey(), params.getBody(), secret);
        return expected.equals(params.getSignature());
    }
}

/**
 * 签名验证拦截器
 */
@Component
public class SignatureInterceptor implements HandlerInterceptor {

    @Autowired
    private ApiKeyService apiKeyService;

    @Override
    public boolean preHandle(HttpServletRequest request, HttpServletResponse response,
                            Object handler) throws Exception {
        // 获取请求头
        String apiKey = request.getHeader("Authorization").replace("ApiKey ", "");
        String timestamp = request.getHeader("X-Timestamp");
        String nonce = request.getHeader("X-Nonce");
        String signature = request.getHeader("X-Signature");

        // 获取请求体
        String body = getRequestBody(request);

        // 查询API密钥
        ApiKeyInfo keyInfo = apiKeyService.getByApiKey(apiKey);
        if (keyInfo == null) {
            throw new AuthenticationException("无效的API Key");
        }

        // 验证签名
        SignatureParams params = new SignatureParams(timestamp, nonce, apiKey, body, signature);
        if (!ApiSignatureUtil.verify(params, keyInfo.getSecret())) {
            throw new AuthenticationException("签名验证失败");
        }

        // 设置上下文
        ApiContext.setCurrentApiKey(keyInfo);
        return true;
    }
}

### 4.3 限流设计

**限流维度**：

| 维度 | 说明 | 示例 |
|-----|-----|-----|
| 全局限流 | 整个API的总QPS | 10000 QPS |
| 接口限流 | 单个接口的QPS | 创建订单 1000 QPS |
| 用户限流 | 单个用户的QPS | 每用户 100 QPS |
| IP限流 | 单个IP的QPS | 每IP 50 QPS |

**基于Redis的限流实现**：

```java
/**
 * 滑动窗口限流器
 */
@Component
public class RateLimiter {

    @Autowired
    private StringRedisTemplate redisTemplate;

    /**
     * 检查是否允许请求
     * @param key 限流key
     * @param limit 限制次数
     * @param windowSeconds 窗口时间（秒）
     */
    public boolean isAllowed(String key, int limit, int windowSeconds) {
        long now = System.currentTimeMillis();
        long windowStart = now - windowSeconds * 1000L;

        String redisKey = "rate_limit:" + key;

        // 使用Lua脚本保证原子性
        String script = """
            -- 移除窗口外的记录
            redis.call('ZREMRANGEBYSCORE', KEYS[1], 0, ARGV[1])
            -- 获取当前窗口内的请求数
            local count = redis.call('ZCARD', KEYS[1])
            if count < tonumber(ARGV[2]) then
                -- 添加当前请求
                redis.call('ZADD', KEYS[1], ARGV[3], ARGV[3])
                redis.call('EXPIRE', KEYS[1], ARGV[4])
                return 1
            else
                return 0
            end
            """;

        Long result = redisTemplate.execute(
            new DefaultRedisScript<>(script, Long.class),
            List.of(redisKey),
            String.valueOf(windowStart),
            String.valueOf(limit),
            String.valueOf(now),
            String.valueOf(windowSeconds)
        );

        return result != null && result == 1;
    }
}

/**
 * 限流注解
 */
@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
public @interface RateLimit {
    int limit() default 100;        // 限制次数
    int window() default 60;        // 窗口时间（秒）
    String key() default "";        // 限流key，支持SpEL
    LimitType type() default LimitType.IP;  // 限流类型
}

public enum LimitType {
    IP,         // 按IP限流
    USER,       // 按用户限流
    API_KEY,    // 按API Key限流
    GLOBAL      // 全局限流
}

/**
 * 限流切面
 */
@Aspect
@Component
public class RateLimitAspect {

    @Autowired
    private RateLimiter rateLimiter;

    @Around("@annotation(rateLimit)")
    public Object around(ProceedingJoinPoint point, RateLimit rateLimit) throws Throwable {
        String key = buildKey(point, rateLimit);

        if (!rateLimiter.isAllowed(key, rateLimit.limit(), rateLimit.window())) {
            throw new RateLimitException("请求过于频繁，请稍后重试");
        }

        return point.proceed();
    }

    private String buildKey(ProceedingJoinPoint point, RateLimit rateLimit) {
        String baseKey = point.getSignature().toShortString();

        return switch (rateLimit.type()) {
            case IP -> baseKey + ":" + RequestContext.getClientIp();
            case USER -> baseKey + ":" + SecurityContext.getCurrentUserId();
            case API_KEY -> baseKey + ":" + ApiContext.getCurrentApiKey();
            case GLOBAL -> baseKey;
        };
    }
}

@RestController
@RequestMapping("/api/v1/orders")
public class OrderController {

    @PostMapping
    @RateLimit(limit = 100, window = 60, type = LimitType.API_KEY)
    public ApiResponse<OrderResponse> createOrder(@RequestBody CreateOrderRequest request) {
        // 创建订单
    }

    @GetMapping
    @RateLimit(limit = 1000, window = 60, type = LimitType.GLOBAL)
    public ApiResponse<PageResponse<OrderResponse>> listOrders(PageRequest pageRequest) {
        // 查询订单列表
    }
}

/**
 * 使用Resilience4j实现熔断
 */
@Service
public class ExternalApiService {

    @CircuitBreaker(name = "logistics", fallbackMethod = "getTrackingFallback")
    @Retry(name = "logistics")
    @RateLimiter(name = "logistics")
    public TrackingInfo getTracking(String trackingNo) {
        return logisticsClient.getTracking(trackingNo);
    }

    /**
     * 降级方法
     */
    public TrackingInfo getTrackingFallback(String trackingNo, Exception e) {
        log.warn("物流查询降级: trackingNo={}, error={}", trackingNo, e.getMessage());

        // 返回缓存数据
        TrackingInfo cached = trackingCache.get(trackingNo);
        if (cached != null) {
            cached.setFromCache(true);
            return cached;
        }

        // 返回默认值
        TrackingInfo defaultInfo = new TrackingInfo();
        defaultInfo.setTrackingNo(trackingNo);
        defaultInfo.setStatus("UNKNOWN");
        defaultInfo.setMessage("物流信息暂时无法查询");
        return defaultInfo;
    }
}

resilience4j:
  circuitbreaker:
    instances:
      logistics:
        slidingWindowSize: 10
        failureRateThreshold: 50
        waitDurationInOpenState: 30s
        permittedNumberOfCallsInHalfOpenState: 3
  retry:
    instances:
      logistics:
        maxAttempts: 3
        waitDuration: 1s
        retryExceptions:
          - java.io.IOException
          - java.net.SocketTimeoutException
  ratelimiter:
    instances:
      logistics:
        limitForPeriod: 100
        limitRefreshPeriod: 1s
        timeoutDuration: 0

@Configuration
public class OpenApiConfig {

    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
            .info(new Info()
                .title("跨境电商API")
                .version("v1.0")
                .description("跨境电商系统API文档")
                .contact(new Contact()
                    .name("技术团队")
                    .email("tech@example.com")))
            .addSecurityItem(new SecurityRequirement().addList("ApiKey"))
            .components(new Components()
                .addSecuritySchemes("ApiKey",
                    new SecurityScheme()
                        .type(SecurityScheme.Type.APIKEY)
                        .in(SecurityScheme.In.HEADER)
                        .name("Authorization")));
    }
}

@RestController
@RequestMapping("/api/v1/orders")
@Tag(name = "订单管理", description = "订单的创建、查询、更新、取消等操作")
public class OrderController {

    @Operation(
        summary = "创建订单",
        description = "创建新订单，需要传入订单明细、收货地址等信息"
    )
    @ApiResponses({
        @ApiResponse(responseCode = "201", description = "创建成功",
            content = @Content(schema = @Schema(implementation = OrderResponse.class))),
        @ApiResponse(responseCode = "400", description = "参数错误"),
        @ApiResponse(responseCode = "422", description = "业务校验失败，如库存不足")
    })
    @PostMapping
    public ApiResponse<OrderResponse> createOrder(
        @RequestBody @Valid CreateOrderRequest request) {
        // ...
    }

    @Operation(summary = "查询订单列表")
    @Parameters({
        @Parameter(name = "status", description = "订单状态", example = "PENDING"),
        @Parameter(name = "channel", description = "销售渠道", example = "AMAZON"),
        @Parameter(name = "page", description = "页码", example = "1"),
        @Parameter(name = "size", description = "每页条数", example = "20")
    })
    @GetMapping
    public ApiResponse<PageResponse<OrderResponse>> listOrders(
        @RequestParam(required = false) String status,
        @RequestParam(required = false) String channel,
        @Valid PageRequest pageRequest) {
        // ...
    }

    @Operation(summary = "查询订单详情")
    @GetMapping("/{orderId}")
    public ApiResponse<OrderDetailResponse> getOrder(
        @Parameter(description = "订单ID", required = true)
        @PathVariable String orderId) {
        // ...
    }

    @Operation(summary = "取消订单")
    @PostMapping("/{orderId}/cancel")
    public ApiResponse<Void> cancelOrder(
        @PathVariable String orderId,
        @RequestBody CancelOrderRequest request) {
        // ...
    }
}

## 创建订单

### 基本信息

| 项目 | 说明 |
|-----|-----|
| 接口路径 | POST /api/v1/orders |
| 接口描述 | 创建新订单 |
| 认证方式 | API Key + 签名 |
| 限流规则 | 100次/分钟/API Key |

### 请求参数

#### Header参数

| 参数名 | 类型 | 必填 | 说明 |
|-------|-----|-----|-----|
| Authorization | String | 是 | API Key，格式：ApiKey xxx |
| X-Timestamp | String | 是 | 时间戳（毫秒） |
| X-Nonce | String | 是 | 随机字符串 |
| X-Signature | String | 是 | 签名 |

#### Body参数

| 参数名 | 类型 | 必填 | 说明 |
|-------|-----|-----|-----|
| channel | String | 是 | 销售渠道：AMAZON/EBAY/SHOPIFY |
| customerId | String | 是 | 客户ID |
| items | Array | 是 | 订单明细 |
| items[].skuId | String | 是 | SKU编码 |
| items[].quantity | Integer | 是 | 数量，1-9999 |
| items[].unitPrice | Decimal | 是 | 单价 |
| shippingAddress | Object | 是 | 收货地址 |
| totalAmount | Decimal | 是 | 订单总金额 |
| currency | String | 否 | 币种，默认USD |

### 请求示例

```json
{
    "channel": "AMAZON",
    "customerId": "CUST001",
    "items": [
        {
            "skuId": "SKU001",
            "quantity": 2,
            "unitPrice": 99.99
        }
    ],
    "shippingAddress": {
        "name": "John Doe",
        "phone": "+1-123-456-7890",
        "country": "US",
        "state": "CA",
        "city": "Los Angeles",
        "address1": "123 Main St",
        "zipCode": "90001"
    },
    "totalAmount": 199.98,
    "currency": "USD"
}

{
    "code": 0,
    "message": "success",
    "data": {
        "orderId": "ORD202402040001",
        "status": "PENDING",
        "createdAt": 1707033600000
    },
    "timestamp": 1707033600000,
    "traceId": "a1b2c3d4e5f6"
}

{
    "code": 200001,
    "message": "库存不足",
    "data": null,
    "timestamp": 1707033600000,
    "traceId": "a1b2c3d4e5f6",
    "errors": [
        {
            "field": "items[0].quantity",
            "message": "SKU001库存不足，当前可用: 1，请求数量: 2"
        }
    ]
}

@RestController
@RequestMapping("/api/v1/orders")
@Tag(name = "订单管理")
@Validated
public class OrderController {

    @Autowired
    private OrderService orderService;

    /**
     * 创建订单
     */
    @PostMapping
    @ResponseStatus(HttpStatus.CREATED)
    @RateLimit(limit = 100, window = 60, type = LimitType.API_KEY)
    public ApiResponse<OrderResponse> createOrder(
            @RequestBody @Valid CreateOrderRequest request) {
        Order order = orderService.createOrder(request);
        return ApiResponse.success(OrderResponse.from(order));
    }

    /**
     * 查询订单列表
     */
    @GetMapping
    public ApiResponse<PageResponse<OrderResponse>> listOrders(
            @RequestParam(required = false) String status,
            @RequestParam(required = false) String channel,
            @RequestParam(required = false)
            @DateTimeFormat(iso = DateTimeFormat.ISO.DATE) LocalDate startDate,
            @RequestParam(required = false)
            @DateTimeFormat(iso = DateTimeFormat.ISO.DATE) LocalDate endDate,
            @Valid PageRequest pageRequest) {

        OrderQuery query = OrderQuery.builder()
            .status(status)
            .channel(channel)
            .startDate(startDate)
            .endDate(endDate)
            .build();

        Page<Order> page = orderService.listOrders(query, pageRequest.toPageable());
        return ApiResponse.success(PageResponse.of(page.map(OrderResponse::from)));
    }

    /**
     * 查询订单详情
     */
    @GetMapping("/{orderId}")
    public ApiResponse<OrderDetailResponse> getOrder(@PathVariable String orderId) {
        Order order = orderService.getOrder(orderId);
        return ApiResponse.success(OrderDetailResponse.from(order));
    }

    /**
     * 更新订单
     */
    @PatchMapping("/{orderId}")
    public ApiResponse<OrderResponse> updateOrder(
            @PathVariable String orderId,
            @RequestBody @Valid UpdateOrderRequest request) {
        Order order = orderService.updateOrder(orderId, request);
        return ApiResponse.success(OrderResponse.from(order));
    }

    /**
     * 取消订单
     */
    @PostMapping("/{orderId}/cancel")
    public ApiResponse<Void> cancelOrder(
            @PathVariable String orderId,
            @RequestBody @Valid CancelOrderRequest request) {
        orderService.cancelOrder(orderId, request.getReason());
        return ApiResponse.success(null);
    }

    /**
     * 确认订单
     */
    @PostMapping("/{orderId}/confirm")
    public ApiResponse<OrderResponse> confirmOrder(@PathVariable String orderId) {
        Order order = orderService.confirmOrder(orderId);
        return ApiResponse.success(OrderResponse.from(order));
    }

    /**
     * 订单发货
     */
    @PostMapping("/{orderId}/ship")
    public ApiResponse<OrderResponse> shipOrder(
            @PathVariable String orderId,
            @RequestBody @Valid ShipOrderRequest request) {
        Order order = orderService.shipOrder(orderId, request);
        return ApiResponse.success(OrderResponse.from(order));
    }

    /**
     * 获取订单明细
     */
    @GetMapping("/{orderId}/items")
    public ApiResponse<List<OrderItemResponse>> getOrderItems(@PathVariable String orderId) {
        List<OrderItem> items = orderService.getOrderItems(orderId);
        return ApiResponse.success(items.stream()
            .map(OrderItemResponse::from)
            .collect(Collectors.toList()));
    }

    /**
     * 获取订单物流信息
     */
    @GetMapping("/{orderId}/tracking")
    public ApiResponse<TrackingResponse> getOrderTracking(@PathVariable String orderId) {
        TrackingInfo tracking = orderService.getOrderTracking(orderId);
        return ApiResponse.success(TrackingResponse.from(tracking));
    }
}