SpringBoot路由转发实战：5分钟搞定轻量级API网关（附完整代码）

SpringBoot路由转发实战：5分钟搞定轻量级API网关（附完整代码）

最近在帮一个初创团队做技术架构升级，他们面临一个很典型的问题：内部有多个微服务，前端调用起来非常麻烦，每个服务都要单独处理认证、限流和日志。他们不想引入Zuul或Spring Cloud Gateway这类重型网关，觉得维护成本太高，但又需要一个统一的入口来管理这些请求。这让我想起了几年前自己搭建轻量级API网关的经历，用SpringBoot的核心组件，配合一些巧妙的配置，完全可以在短时间内构建一个稳定、可扩展的转发层。

这种轻量级网关的核心价值在于快速响应业务变化。对于中小团队来说，开发资源有限，一个功能齐全但架构复杂的网关反而会成为负担。我们需要的是一个能快速上手、易于理解、并且能解决实际痛点的方案。这篇文章，我就结合自己踩过的坑和积累的经验，手把手带你实现一个功能完备的SpringBoot路由转发服务。它不仅能把请求原封不动地转发到后端服务，还能优雅地处理认证信息透传、请求头过滤、超时控制等细节，并提供完整的异常处理和配置模板。你会发现，用好SpringBoot自带的RestTemplate和拦截器，远比想象中强大。

1. 为什么需要自建轻量级网关？场景与选型分析

在微服务架构成为主流的今天，API网关几乎成了标配。但市面上成熟的网关方案，如Spring Cloud Gateway、Kong、Apigee等，功能强大却也伴随着较高的复杂度和学习成本。对于很多中小型项目或特定内部系统而言，我们可能只需要最核心的路由转发功能，附带一些基础的请求/响应处理。

我遇到过几个典型场景：

• 前端统一对接：前端开发者不想关心后端有多少个服务、地址是什么，他们希望只有一个入口地址。
• 认证与授权解耦：在网关层统一进行JWT校验或OAuth2认证，通过后将用户信息（如userId）以特定请求头（如X-User-Info）的形式透传给下游业务服务，业务服务无需再处理认证逻辑。
• 内部服务聚合：将几个内部服务的调用封装成一个对外的API，减少前端请求次数。
• 快速原型与测试：在开发早期，后端服务可能还不稳定或地址经常变动，通过一个可配置的网关进行转发，能极大提升联调效率。

那么，自建和选用成熟产品如何抉择？我整理了一个简单的对比表格，帮你快速决策：

注意：如果你的项目未来明确会走向复杂的微服务架构，且团队有足够精力维护，那么直接采用Spring Cloud Gateway是更长远的选择。反之，如果你的需求聚焦在“转发”和“简单处理”，那么自建方案在项目初期会是更敏捷、更可控的利器。

我们的目标很明确：在5分钟（当然，是理解核心思路后）内，搭建一个能跑起来的、代码清晰、便于扩展的转发服务。接下来，我们从环境准备开始。

2. 五分钟快速启动：核心骨架与配置

让我们暂时抛开那些复杂的设计模式，先构建一个最小可行产品（MVP）。这个MVP只需要做一件事：接收一个请求，然后把它转发到另一个预设的地址。

首先，创建一个标准的SpringBoot项目，依赖只需要最基础的Web模块。这里我推荐使用Spring Initializr，选择Spring Web依赖即可。

<!-- pom.xml 中的关键依赖 -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
    <groupId>org.apache.httpcomponents</groupId>
    <artifactId>httpclient</artifactId>
    <scope>test</scope>
</dependency>

核心的转发逻辑在一个Controller和一个Service里。我们先看Controller，它负责拦截所有匹配特定模式的请求。

import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;

@RestController
@RequestMapping("/gateway") // 网关的统一入口前缀
public class GatewayController {

    @Autowired
    private GatewayRouter gatewayRouter;

    /**
     * 通配符匹配所有路径，{serviceId}用于标识要转发的目标服务
     * 支持 GET, POST, PUT, DELETE 等常用方法
     */
    @RequestMapping(value = "/{serviceId}/**", method = {RequestMethod.GET, RequestMethod.POST, RequestMethod.PUT, RequestMethod.DELETE, RequestMethod.PATCH})
    public ResponseEntity<byte[]> route(
            @PathVariable("serviceId") Strin