一、为什么要“优雅”？
产品一句话： “凡哥，接口明天上线，支持 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 & 分布式锁双保险）
对于一些涉及到数据一致性的接口一定要做好幂等设计，以防数据出现重复问题
思路
下单前先申请一个幂等 Token（存在 Redis，5 分钟失效）。
下单时带着 Token，后端用 Lua 脚本“判断存在并删除”，原子性保证只能用一次。
对并发极高场景，再补一层分布式锁（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接口的稳定性至关重要。
起服务：
java -jar -Xms1g -Xmx1g demo-api.jar
JMeter 线程组：
500 线程、Ramp-up 10s、循环 20。
观测：
Sentinel 控制台看 QPS、RT
top -H 看 CPU
arthas 火焰图找慢方法
调优：
限流阈值 = 压测 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% 的生产场景。
祝你在领导问起接口怎么样了？的时候，可以淡淡来一句：
