接口开发，咱得整得“优雅”点

大家好，我是晓凡。

一、为什么要"优雅"？

产品一句话： "凡哥，接口明天上线，支持 10w 并发，数据脱敏，不能丢单，不能重复，还要安全。"

优雅不是装，是为了让自己少加班、少背锅、少掉发。

今天晓凡就把压箱底的东西掏出来，手把手带你撸一套能扛生产的模板。

为方便阅读，晓凡以Java代码为例给出"核心代码 + 使用姿势"，全部亲测可直接使用。

二、项目骨架（Spring Boot 3.x）

demo-api
├── src/main/java/com/example/demo
│   ├── config          // 配置：限流、加解密、日志等
│   ├── annotation      // 自定义注解（幂等、日志、脱敏）
│   ├── aspect          // 切面统一干活
│   ├── interceptor     // 拦截器（签名、白名单）
│   ├── common          // 统一返回、异常、常量
│   ├── controller      // 对外暴露
│   ├── service
│   └── DemoApplication.java
└── pom.xml

三、 签名（防篡改）

对外提供的接口要做签名认证，认证不通过的请求不允许访问接口、提供服务

思路

"时间戳 + 随机串 + 业务参数"排好序，最后 APP_SECRET 拼后面，SHA256 一下。

前后端、第三方都统一，拒绝撕逼。

工具类

public class SignUtil {
    /**
     * 生成签名
     * @param map  除 sign 外的所有参数
     * @param secret 分配给你的私钥
     */
    public static String sign(Map<String, String> map, String secret) {
        // 1. 参数名升序排列
        Map<String, String> tree = new TreeMap<>(map);
        // 2. 拼成 k=v&k=v
        String join = tree.entrySet().stream()
                .map(e -> e.getKey() + "=" + e.getValue())
                .collect(Collectors.joining("&"));
        // 3. 最后拼密钥
        String raw = join + "&key=" + secret;
        // 4. SHA256
        return DigestUtils.sha256Hex(raw).toUpperCase();
    }

    /** 验签：直接比对即可 */
    public static boolean verify(Map<String, String> map, String secret, String requestSign) {
        return sign(map, secret).equals(requestSign);
    }
}

拦截器统一验签

@Component
public class SignInterceptor implements HandlerInterceptor {
    @Value("${sign.secret}")
    private String secret;

    @Override
    public boolean preHandle(HttpServletRequest request,
                             HttpServletResponse response,
                             Object handler) throws Exception {
        // 只拦截接口
        if (!(handler instanceof HandlerMethod)) return true;

        Map<String, String> params = Maps.newHashMap();
        request.getParameterMap().forEach((k, v) -> params.put(k, v[0]));

        String sign = params.remove("sign");   // 签名不参与计算
        if (!SignUtil.verify(params, secret, sign)) {
            throw new BizException("签名错误");
        }
        return true;
    }
}

四、 加密（防泄露）

敏感数据在网络传输过程中都应该加密处理

思路
AES 对称加密，密钥放配置中心，支持一键开关。

只对敏感字段加密，别一上来全包加密，排查日志想打人。

AES 工具

public class AesUtil {
    private static final String ALG = "AES/CBC/PKCS5Padding";
    // 16 位
    private static final String KEY = "1234567890abcdef";
    private static final String IV  = "abcdef1234567890";

    public static String encrypt(String src) {
        try {
            Cipher cipher = Cipher.getInstance(ALG);
            SecretKeySpec keySpec = new SecretKeySpec(KEY.getBytes(), "AES");
            IvParameterSpec ivSpec = new IvParameterSpec(IV.getBytes());
            cipher.init(Cipher.ENCRYPT_MODE, keySpec, ivSpec);
            return Base64.getEncoder().encodeToString(cipher.doFinal(src.getBytes()));
        } catch (Exception e) {
            throw new RuntimeException("加密失败", e);
        }
    }

    public static String decrypt(String src) {
        try {
            Cipher cipher = Cipher.getInstance(ALG);
            SecretKeySpec keySpec = new SecretKeySpec(KEY.getBytes(), "AES");
            IvParameterSpec ivSpec = new IvParameterSpec(IV.getBytes());
            cipher.init(Cipher.DECRYPT_MODE, keySpec, ivSpec);
            return new String(cipher.doFinal(Base64.getDecoder().decode(src)));
        } catch (Exception e) {
            throw new RuntimeException("解密失败", e);
        }
    }
}

五、 IP 白名单

限制请求的IP，增加IP白名单，一般在网关层处理

配置

white:
  ips: 127.0.0.1,10.0.0.0/8,192.168.0.0/16

拦截器

@Component
public class WhiteListInterceptor implements HandlerInterceptor {
    @Value("#{'${white.ips}'.split(',')}")
    private List<String> allowList;

    @Override
    public boolean preHandle(HttpServletRequest request,
                             HttpServletResponse response,
                             Object handler) throws Exception {
        String ip = IpUtil.getIp(request);
        boolean ok = allowList.stream()
                .anyMatch(rule -> IpUtil.match(ip, rule));
        if (!ok) throw new BizException("IP 不允许访问");
        return true;
    }
}

六、 限流（Sentinel 注解版）

尤其对外提供的接口，无法保障调用频率，应该做限流处理，保障接口服务正常的提供服务

依赖

<dependency>
    <groupId>com.alibaba.csp</groupId>
    <artifactId>sentinel-spring-boot-starter</artifactId>
    <version>1.8.6</version>
</dependency>

配置

spring:
  application:
    name: demo-api
sentinel:
  transport:
    dashboard: localhost:8080

使用姿势

@GetMapping("/order/{id}")
@SentinelResource(value = "getOrder",
        blockHandler = "getOrderBlock")
public Result<OrderVO> getOrder(@PathVariable Long id) {
    return Result.success(orderService.get(id));
}

// 限流兜底
public Result<OrderVO> getOrderBlock(Long id, BlockException e) {
    return Result.fail("访问太频繁，稍后再试");
}

七、 参数校验（JSR303 + 分组）

即使前端做了非空，规范性校验，服务端参数校验任然是必不可少的

DTO

public class OrderCreateDTO {
    @NotNull(message = "用户 ID 不能为空")
    private Long userId;

    @NotEmpty(message = "商品列表不能为空")
    @Size(max = 20, message = "一次最多买 20 件")
    private List<Item> items;

    @Valid
    @NotNull
    private PayInfo payInfo;

    @Data
    public static class PayInfo {
        @Min(value = 1, message = "金额必须大于 0")
        private Integer amount;
    }
}

分组接口

public interface Create {}

Controller

@PostMapping("/order")
public Result<Long> create(@RequestBody @Validated(Create.class) OrderCreateDTO dto) {
    Long orderId = orderService.create(dto);
    return Result.success(orderId);
}

八、 统一返回值

提供统一的返回结果，不应该返回值五花八门

@Data
@AllArgsConstructor
@NoArgsConstructor
public class Result<T> implements Serializable {
    private int code;
    private String msg;
    private T data;

    public static <T> Result<T> success(T data) {
        return new Result<>(200, "success", data);
    }

    public static <T> Result<T> fail(String msg) {
        return new Result<>(500, msg, null);
    }

    /** 返回 200 但提示业务失败 */
    public static <T> Result<T> bizFail(int code, String msg) {
        return new Result<>(code, msg, null);
    }
}

九、 统一异常处理

系统报错信息需要提供友好的提示，避免暴露出SQL异常的信息给调用方和客户端。

@RestControllerAdvice
public class GlobalExceptionHandler {
    private static final Logger log = LoggerFactory.getLogger(GlobalExceptionHandler.class);

    /** 业务异常 */
    @ExceptionHandler(BizException.class)
    public Result<Void> handle(BizException e) {
        log.warn("业务异常：{}", e.getMessage());
        return Result.bizFail(e.getCode(), e.getMessage());
    }

    /** 参数校验失败 */
    @ExceptionHandler(MethodArgumentNotValidException.class)
    public Result<Void> handleValid(MethodArgumentNotValidException e) {
        String msg = e.getBindingResult()
                .getFieldErrors()
                .stream()
                .map(DefaultMessageSourceResolvable::getDefaultMessage)
                .collect(Collectors.joining(","));
        return Result.fail(msg);
    }

    /** 兜底 */
    @ExceptionHandler(Exception.class)
    public Result<Void> handleAll(Exception e) {
        log.error("系统异常", e);
        return Result.fail("服务器开小差");
    }
}

十、 请求日志（切面 + 注解）

记录请求的入参日志和返回日志，出问题时方便快速定位。也给运维人员提供了方便

注解

@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
public @interface ApiLog {}

切面

@Aspect
@Component
public class LogAspect {
    private static final Logger log = LoggerFactory.getLogger("api.log");

    @Around("@annotation(apiLog)")
    public Object around(ProceedingJoinPoint p, ApiLog apiLog) throws Throwable {
        long start = System.currentTimeMillis();
        ServletRequestAttributes attr =
                (ServletRequestAttributes) RequestContextHolder.getRequestAttributes();
        HttpServletRequest req = attr.getRequest();

        String uri = req.getRequestURI();
        String params = JSON.toJSONString(p.getArgs());

        Object result;
        try {
            result = p.proceed();
        } catch (Exception e) {
            log.error("【{}】params={} error={}", uri, params, e.getMessage());
            throw e;
        } finally {
            long cost = System.currentTimeMillis() - start;
            log.info("【{}】params={} cost={}ms", uri, params, cost);
        }
        return result;
    }
}

用法

@ApiLog
@PostMapping("/order")
public Result<Long> create(...) {}

十一、幂等设计（Token & 分布式锁双保险）

对于一些涉及到数据一致性的接口一定要做好幂等设计，以防数据出现重复问题

思路

1. 下单前先申请一个幂等 Token（存在 Redis，5 分钟失效）。
2. 下单时带着 Token，后端用 Lua 脚本"判断存在并删除"，原子性保证只能用一次。
3. 对并发极高场景，再补一层分布式锁（Redisson）。

代码

@Service
public class IdempotentService {
    @Resource
    private StringRedisTemplate redis;

    /** 申请 Token */
    public String createToken() {
        String token = UUID.fastUUID().toString();
        redis.opsForValue().set("token:" + token, "1",
                Duration.ofMinutes(5));
        return token;
    }

    /** 验证并删除 */
    public boolean checkToken(String token) {
        String key = "token:" + token;
        // 原子删除成功才算用过
        return Boolean.TRUE.equals(redis.delete(key));
    }
}

Controller

@GetMapping("/token")
public Result<String> getToken() {
    return Result.success(idempotentService.createToken());
}

@PostMapping("/order")
@ApiLog
public Result<Long> create(@RequestBody @Valid OrderCreateDTO dto,
                           @RequestHeader("Idempotent-Token") String token) {
    if (!idempotentService.checkToken(token)) {
        throw new BizException("请勿重复提交");
    }
    Long orderId = orderService.create(dto);
    return Result.success(orderId);
}

十二、限制记录条数（分页 + SQL 保护）

对于批量数据接口，一定要限制返回的记录条数，不让会造成恶意攻击导致服务器宕机。

MyBatis-Plus 分页插件

@Configuration
public class MybatisConfig {
    @Bean
    public MybatisPlusInterceptor interceptor() {
        MybatisPlusInterceptor i = new MybatisPlusInterceptor();
        i.addInnerInterceptor(new PaginationInnerInterceptor(DbType.MYSQL));
        return i;
    }
}

Service

public Page<OrderVO> list(OrderListDTO dto) {
    // 前端不传默认 10 条，最多 200
    long size = Math.min(dto.getPageSize(), 200);
    Page<Order> page = new Page<>(dto.getPageNo(), size);
    LambdaQueryWrapper<Order> w = Wrappers.lambdaQuery();
    if (StrUtil.isNotBlank(dto.getUserName())) {
        w.like(Order::getUserName, dto.getUserName());
    }
    Page<Order> po = orderMapper.selectPage(page, w);
    return po.convert(o -> BeanUtil.copyProperties(o, OrderVO.class));
}

十三、 压测（JMeter + 自带脚本）

上线前，务必要对API接口进行压力测试，知道各个接口的qps情况。以便我们能够更好的预估，需要部署多少服务节点，对于API接口的稳定性至关重要。

1. 起服务：
   java -jar -Xms1g -Xmx1g demo-api.jar

2. JMeter 线程组：

   500 线程、Ramp-up 10s、循环 20。

3. 观测：

   • Sentinel 控制台看 QPS、RT
   • top -H 看 CPU
   • arthas 火焰图找慢方法

4. 调优：

   • 限流阈值 = 压测 80% 最高水位
   • 发现慢 SQL 加索引
   • 热点数据加本地缓存（Caffeine）

十四、异步处理

如果同步处理业务，耗时会非常长。这种情况下，为了提升API接口性能，我们可以改为异步处理

下单成功后，发 MQ 异步发短信/扣库存，接口 RT 直接降一半。

@Async("asyncExecutor")   // 自定义线程池
public void sendSmsAsync(Long userId, String content) {
    smsService.send(userId, content);
}

十五、数据脱敏

业务中对与用户的敏感数据，如密码等需要进行脱敏处理

返回前统一用 Jackson 序列化过滤器，字段加注解就行，代码零侵入。

@JsonSerialize(using = SensitiveSerializer.class)
@Target(ElementType.FIELD)
@Retention(RetentionPolicy.RUNTIME)
public @interface Sensitive {
    SensitiveType type();
}

public enum SensitiveType {
    PHONE, ID_CARD, BANK_CARD
}

public class SensitiveSerializer extends JsonSerializer<String> {
    @Override
    public void serialize(String value, JsonGenerator g, SerializerProvider p)
            throws IOException {
        if (StrUtil.isBlank(value)) {
            g.writeString(value);
            return;
        }
        g.writeString(DesensitizeUtil.desPhone(value));
    }
}

十六、完整的接口文档（Knife4j）

提供在线接口文档，既方便开发调试接口，也方便运维人员排查错误

依赖

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-openapi3-spring-boot-starter</artifactId>
    <version>4.1.0</version>
</dependency>

配置

knife4j:
  enable: true
  setting:
    language: zh_cn

启动后访问
http://localhost:8080/doc.html

支持在线调试、导出 PDF、Word。

十七、小结

接口开发就像炒菜：

• 签名、加密是"食材保鲜"
• 限流、幂等是"火候掌控"
• 日志、文档是"摆盘拍照"

每道工序做到位，才能端到桌上"色香味"俱全。

上面 13 段核心代码，直接粘过去就能跑，跑通后再按业务微调，基本能扛 90% 的生产场景。

祝你在领导问起接口怎么样了？的时候，可以淡淡来一句：

"接口已经准备好了，压测报告发群里了。"