Spring Security 是一个轻量级的安全框架，可以和 Spring 项目很好地集成，提供了丰富的身份认证和授权相关的功能，而且还能防止一些常见的网络攻击。我在工作中有很多项目都使用了 Spring Security 框架，但基本上都是浅尝辄止，按照说明文档配置好就完事了，一直没有时间深入地研究过。最近在 Reflectoring 上看到了一篇文章 Getting started with Spring Security and Spring Boot，写得非常全面仔细，感觉是一篇不错的 Spring Security 入门文章，于是花了一点时间拜读了一番，结合着 官方文档 和 源码 系统地学习一下 Spring Security 的实现原理。

入门示例

我们先从一个简单的例子开始，这里我直接使用了 使用 Spring 项目脚手架 中的 Hello World 示例。为了让这个示例程序开启 Spring Security 功能，我们在 pom.xml 文件中引入 spring-boot-starter-security 依赖即可：

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-security</artifactId>
</dependency>

启动程序，会在控制台日志中看到类似下面这样的信息：

2023-05-15 06:52:52.418  INFO 8596 --- [           main] .s.s.UserDetailsServiceAutoConfiguration : 

Using generated security password: eeb386a9-e16a-4b9b-bbc6-c054c8d263b0

这个是由 Spring Security 随机生成的密码。访问 /hello 页面，可以看到出现了一个登录页面：

输入用户名（默认为 user）和密码（控制台日志）登录成功后我们才能正常访问页面。默认的用户名和密码可以使用下面的配置进行修改：

spring.security.user.name=admin
spring.security.user.password=123456

为了后续更好地对 Spring Security 进行配置，理解 Spring Security 的实现原理，我们需要进一步学习 Spring Security 的三大核心组件：

• 过滤器（Servlet Filters）
• 认证（Authentication）
• 授权（Authorization）

Servlet Filters：Spring Security 的基础

我们知道，在 Spring MVC 框架中，DispatcherServlet 负责对用户的 Web 请求进行分发和处理，在请求到达 DispatcherServlet 之前，会经过一系列的 Servlet Filters，这被称之为过滤器，主要作用是拦截请求并对请求做一些前置或后置处理。这些过滤器串在一起，形成一个过滤器链（FilterChain）：

我们可以在配置文件中加上下面的日志配置：

logging.level.org.springframework.boot.web.servlet.ServletContextInitializerBeans=TRACE

然后重新启动服务，会在控制台输出类似下面这样的日志（为了方便查看，我做了一点格式化）：

2023-05-18 07:08:14.805 TRACE 10020 --- [           main] o.s.b.w.s.ServletContextInitializerBeans : 
    Added existing Filter initializer bean 'webMvcMetricsFilter'; order=-2147483647, 
    resource=class path resource [org/springframework/boot/actuate/autoconfigure/metrics/web/servlet/WebMvcMetricsAutoConfiguration.class]
2023-05-18 07:08:14.806 TRACE 10020 --- [           main] o.s.b.w.s.ServletContextInitializerBeans : 
    Added existing Filter initializer bean 'securityFilterChainRegistration'; order=-100, 
    resource=class path resource [org/springframework/boot/autoconfigure/security/servlet/SecurityFilterAutoConfiguration.class]
2023-05-18 07:08:14.808 TRACE 10020 --- [           main] o.s.b.w.s.ServletContextInitializerBeans : 
    Added existing Servlet initializer bean 'dispatcherServletRegistration'; order=2147483647, 
    resource=class path resource [org/springframework/boot/autoconfigure/web/servlet/DispatcherServletAutoConfiguration$DispatcherServletRegistrationConfiguration.class]
2023-05-18 07:08:14.810 TRACE 10020 --- [           main] o.s.b.w.s.ServletContextInitializerBeans : 
    Added existing Filter initializer bean 'errorPageSecurityFilter'; order=2147483647, 
    resource=class path resource [org/springframework/boot/autoconfigure/security/servlet/SpringBootWebSecurityConfiguration$ErrorPageSecurityFilterConfiguration.class]
2023-05-18 07:08:14.813 TRACE 10020 --- [           main] o.s.b.w.s.ServletContextInitializerBeans : 
    Added existing ServletContextInitializer initializer bean 'servletEndpointRegistrar'; order=2147483647, 
    resource=class path resource [org/springframework/boot/actuate/autoconfigure/endpoint/web/ServletEndpointManagementContextConfiguration$WebMvcServletEndpointManagementContextConfiguration.class]
2023-05-18 07:08:14.828 TRACE 10020 --- [           main] o.s.b.w.s.ServletContextInitializerBeans : 
    Created Filter initializer for bean 'characterEncodingFilter'; order=-2147483648, 
    resource=class path resource [org/springframework/boot/autoconfigure/web/servlet/HttpEncodingAutoConfiguration.class]    
2023-05-18 07:08:14.831 TRACE 10020 --- [           main] o.s.b.w.s.ServletContextInitializerBeans : 
    Created Filter initializer for bean 'formContentFilter'; order=-9900, 
    resource=class path resource [org/springframework/boot/autoconfigure/web/servlet/WebMvcAutoConfiguration.class]
2023-05-18 07:08:14.834 TRACE 10020 --- [           main] o.s.b.w.s.ServletContextInitializerBeans : 
    Created Filter initializer for bean 'requestContextFilter'; order=-105, 
    resource=class path resource [org/springframework/boot/autoconfigure/web/servlet/WebMvcAutoConfiguration$WebMvcAutoConfigurationAdapter.class]
2023-05-18 07:08:14.842 DEBUG 10020 --- [           main] o.s.b.w.s.ServletContextInitializerBeans : 
    Mapping filters: 
        filterRegistrationBean urls=[/*] order=-2147483647, 
        springSecurityFilterChain urls=[/*] order=-100, 
        filterRegistrationBean urls=[/*] order=2147483647, 
        characterEncodingFilter urls=[/*] order=-2147483648, 
        formContentFilter urls=[/*] order=-9900, 
        requestContextFilter urls=[/*] order=-105
2023-05-18 07:08:14.844 DEBUG 10020 --- [           main] o.s.b.w.s.ServletContextInitializerBeans : 
    Mapping servlets: dispatcherServlet urls=[/] 

这里显示了应用开启的所有 Filter 以及对应的自动配置类，可以看到 Spring Security 自动注入了两个 FilterRegistrationBean：

• 来自配置类 SecurityFilterAutoConfiguration 的 securityFilterChainRegistration
• 来自配置类 ErrorPageSecurityFilterConfiguration 的 errorPageSecurityFilter

DelegatingFilterProxy：Servlet Filter 与 Spring Bean 的桥梁

注意上面显示的并非 Filter 的名字，而是 FilterRegistrationBean 的名字，这是一种 RegistrationBean，它实现了 ServletContextInitializer 接口，用于在程序启动时，将 Filter 或 Servlet 注入到 ServletContext 中：

public abstract class RegistrationBean implements ServletContextInitializer, Ordered {

    @Override
    public final void onStartup(ServletContext servletContext) throws ServletException {
        ...
        register(description, servletContext);
    }

}

其中 securityFilterChainRegistration 的定义如下：

@Bean
@ConditionalOnBean(name = DEFAULT_FILTER_NAME)
public DelegatingFilterProxyRegistrationBean securityFilterChainRegistration(
        SecurityProperties securityProperties) {
    DelegatingFilterProxyRegistrationBean registration = new DelegatingFilterProxyRegistrationBean(
            DEFAULT_FILTER_NAME);
    registration.setOrder(securityProperties.getFilter().getOrder());
    registration.setDispatcherTypes(getDispatcherTypes(securityProperties));
    return registration;
}

这个 RegistrationBean 的类型为 DelegatingFilterProxyRegistrationBean，由它注入的 Filter 叫 DelegatingFilterProxy：

public class DelegatingFilterProxyRegistrationBean extends AbstractFilterRegistrationBean<DelegatingFilterProxy> {
    ...
}

这是一个非常重要的 Servlet Filter，它充当着 Servlet 容器和 Spring 上下文之间的桥梁，由于 Servlet 容器有着它自己的标准，在注入 Filter 时并不知道 Spring Bean 的存在，所以我们可以通过 DelegatingFilterProxy 来实现 Bean Filter 的延迟加载：

看一下 DelegatingFilterProxy 的实现：

public class DelegatingFilterProxy extends GenericFilterBean {

    @Override
    public void doFilter(ServletRequest request, ServletResponse response, FilterChain filterChain)
            throws ServletException, IOException {

        // Lazily initialize the delegate if necessary.
        Filter delegateToUse = this.delegate;
        if (delegateToUse == null) {
            synchronized (this.delegateMonitor) {
                delegateToUse = this.delegate;
                if (delegateToUse == null) {
                    WebApplicationContext wac = findWebApplicationContext();
                    if (wac == null) {
                        throw new IllegalStateException("No WebApplicationContext found: " +
                                "no ContextLoaderListener or DispatcherServlet registered?");
                    }
                    delegateToUse = initDelegate(wac);
                }
                this.delegate = delegateToUse;
            }
        }

        // Let the delegate perform the actual doFilter operation.
        invokeDelegate(delegateToUse, request, response, filterChain);
    }
}

这段代码很容易理解，首先判断代理的 Bean Filter 是否存在，如果不存在则根据 findWebApplicationContext() 找到 Web 应用上下文，然后从上下文中获取 Bean Filter 并初始化，最后再调用该 Bean Filter。

FilterChainProxy：Spring Security 的统一入口

那么接下来的问题是，这个 DelegatingFilterProxy 代理的 Bean Filter 是什么呢？我们从上面定义 DelegatingFilterProxyRegistrationBean 的地方可以看出，代理的 Bean Filter 叫做 DEFAULT_FILTER_NAME，查看它的定义就知道，实际上就是 springSecurityFilterChain：

public static final String DEFAULT_FILTER_NAME = "springSecurityFilterChain";

那么这个 springSecurityFilterChain 是在哪定义的呢？我们可以在 WebSecurityConfiguration 配置类中找到答案：

public class WebSecurityConfiguration {

    @Bean(name = AbstractSecurityWebApplicationInitializer.DEFAULT_FILTER_NAME)
    public Filter springSecurityFilterChain() throws Exception {
        boolean hasConfigurers = this.webSecurityConfigurers != null && !this.webSecurityConfigurers.isEmpty();
        boolean hasFilterChain = !this.securityFilterChains.isEmpty();
        if (!hasConfigurers && !hasFilterChain) {
            WebSecurityConfigurerAdapter adapter = this.objectObjectPostProcessor
                    .postProcess(new WebSecurityConfigurerAdapter() {
                    });
            this.webSecurity.apply(adapter);
        }
        for (SecurityFilterChain securityFilterChain : this.securityFilterChains) {
            this.webSecurity.addSecurityFilterChainBuilder(() -> securityFilterChain);
            for (Filter filter : securityFilterChain.getFilters()) {
                if (filter instanceof FilterSecurityInterceptor) {
                    this.webSecurity.securityInterceptor((FilterSecurityInterceptor) filter);
                    break;
                }
            }
        }
        for (WebSecurityCustomizer customizer : this.webSecurityCustomizers) {
            customizer.customize(this.webSecurity);
        }
        return this.webSecurity.build();
    }
}

很显然，springSecurityFilterChain 经过一系列的安全配置，最后通过 this.webSecurity.build() 构建出来的，进一步深入到 webSecurity 的源码我们就可以发现它的类型是 FilterChainProxy：

public final class WebSecurity extends AbstractConfiguredSecurityBuilder<Filter, WebSecurity>
        implements SecurityBuilder<Filter>, ApplicationContextAware, ServletContextAware {

    @Override
    protected Filter performBuild() throws Exception {

        int chainSize = this.ignoredRequests.size() + this.securityFilterChainBuilders.size();
        List<SecurityFilterChain> securityFilterChains = new ArrayList<>(chainSize);
        List<RequestMatcherEntry<List<WebInvocationPrivilegeEvaluator>>> requestMatcherPrivilegeEvaluatorsEntries = new ArrayList<>();
        for (RequestMatcher ignoredRequest : this.ignoredRequests) {
            SecurityFilterChain securityFilterChain = new DefaultSecurityFilterChain(ignoredRequest);
            securityFilterChains.add(securityFilterChain);
            requestMatcherPrivilegeEvaluatorsEntries
                    .add(getRequestMatcherPrivilegeEvaluatorsEntry(securityFilterChain));
        }
        for (SecurityBuilder<? extends SecurityFilterChain> securityFilterChainBuilder : this.securityFilterChainBuilders) {
            SecurityFilterChain securityFilterChain = securityFilterChainBuilder.build();
            securityFilterChains.add(securityFilterChain);
            requestMatcherPrivilegeEvaluatorsEntries
                    .add(getRequestMatcherPrivilegeEvaluatorsEntry(securityFilterChain));
        }

        FilterChainProxy filterChainProxy = new FilterChainProxy(securityFilterChains);
        if (this.httpFirewall != null) {
            filterChainProxy.setFirewall(this.httpFirewall);
        }
        if (this.requestRejectedHandler != null) {
            filterChainProxy.setRequestRejectedHandler(this.requestRejectedHandler);
        }
        filterChainProxy.afterPropertiesSet();

        Filter result = filterChainProxy;

        this.postBuildAction.run();
        return result;
    }
}

从 FilterChainProxy 的名字可以看出来，它也是一个代理类，它代理的类叫做 SecurityFilterChain，它包含了多个 Security Filters 形成一个过滤器链，这和 Servlet Filters 有点类似，只不过这些 Security Filters 都是普通的 Spring Bean：

使用 FilterChainProxy 来代理 Security Filters 相比于直接使用 Servlet Filters 或使用 DelegatingFilterProxy 来代理有几个明显的好处：

1. FilterChainProxy 作为 Spring Security 对 Servlet 的支持入口，方便理解和调试；
2. FilterChainProxy 可以对 Spring Security 做一些集中处理，比如统一清除 SecurityContext 防止内存泄漏，以及统一使用 HttpFirewall 对应用进行保护等；
3. 支持多个 SecurityFilterChain，传统的 Servlet Filters 只能通过 URL 来匹配，使用 FilterChainProxy 可以配合 RequestMatcher 更灵活地控制调用哪个 SecurityFilterChain；

构建 SecurityFilterChain

上面讲到，FilterChainProxy 是通过 webSecurity 构建的，一个 FilterChainProxy 里包含一个或多个 SecurityFilterChain，那么 SecurityFilterChain 是由谁构建的呢？答案是 httpSecurity。我们可以在 SecurityFilterChainConfiguration 配置类中看到 SecurityFilterChain 的构建过程：

@Configuration(proxyBeanMethods = false)
@ConditionalOnDefaultWebSecurity
static class SecurityFilterChainConfiguration {

    @Bean
    @Order(SecurityProperties.BASIC_AUTH_ORDER)
    SecurityFilterChain defaultSecurityFilterChain(HttpSecurity http) throws Exception {
        http.authorizeRequests().anyRequest().authenticated();
        http.formLogin();
        http.httpBasic();
        return http.build();
    }
}

深入到 http.build() 的源码，可以看到过滤器链的默认实现为 DefaultSecurityFilterChain：

public final class HttpSecurity extends AbstractConfiguredSecurityBuilder<DefaultSecurityFilterChain, HttpSecurity>
        implements SecurityBuilder<DefaultSecurityFilterChain>, HttpSecurityBuilder<HttpSecurity> {

    @SuppressWarnings("unchecked")
    @Override
    protected DefaultSecurityFilterChain performBuild() {

        this.filters.sort(OrderComparator.INSTANCE);
        List<Filter> sortedFilters = new ArrayList<>(this.filters.size());
        for (Filter filter : this.filters) {
            sortedFilters.add(((OrderedFilter) filter).filter);
        }
        return new DefaultSecurityFilterChain(this.requestMatcher, sortedFilters);
    }
}

构建 Security Filters

通过上面的梳理，我们大概清楚了 SecurityFilterChain 的构建过程，接下来，我们继续看 Security Filters 的构建过程。我们知道，一个SecurityFilterChain 中包含了多个 Security Filters，那么这些 Security Filters 是从哪里来的呢？

在 HttpSecurity 的代码里可以找到这么几个方法：

• public HttpSecurity addFilter(Filter filter)
• public HttpSecurity addFilterBefore(Filter filter, Class<? extends Filter> beforeFilter)
• public HttpSecurity addFilterAfter(Filter filter, Class<? extends Filter> afterFilter)
• public HttpSecurity addFilterAt(Filter filter, Class<? extends Filter> atFilter)

我们不妨在 addFilter 方法内下个断点，然后以调试模式启动程序，每次触发断点时，我们将对应的 Filter 记录下来，并通过堆栈找到该 Filter 是从何处添加的：

除了第一个 WebAsyncManagerIntegrationFilter 是在创建 HttpSecurity 的时候直接添加的，其他的 Filter 都是通过 XXXConfigurer 这样的配置器添加的。我们继续深挖下去可以发现，生成这些配置器的地方有两个，第一个地方是在 HttpSecurityConfiguration 配置类中创建 HttpSecurity 时，如下所示：

class HttpSecurityConfiguration {

    @Bean(HTTPSECURITY_BEAN_NAME)
    @Scope("prototype")
    HttpSecurity httpSecurity() throws Exception {
        WebSecurityConfigurerAdapter.LazyPasswordEncoder passwordEncoder = new WebSecurityConfigurerAdapter.LazyPasswordEncoder(
                this.context);
        AuthenticationManagerBuilder authenticationBuilder = new WebSecurityConfigurerAdapter.DefaultPasswordEncoderAuthenticationManagerBuilder(
                this.objectPostProcessor, passwordEncoder);
        authenticationBuilder.parentAuthenticationManager(authenticationManager());
        authenticationBuilder.authenticationEventPublisher(getAuthenticationEventPublisher());
        HttpSecurity http = new HttpSecurity(this.objectPostProcessor, authenticationBuilder, createSharedObjects());
        // @formatter:off
        http
            .csrf(withDefaults())
            .addFilter(new WebAsyncManagerIntegrationFilter())
            .exceptionHandling(withDefaults())
            .headers(withDefaults())
            .sessionManagement(withDefaults())
            .securityContext(withDefaults())
            .requestCache(withDefaults())
            .anonymous(withDefaults())
            .servletApi(withDefaults())
            .apply(new DefaultLoginPageConfigurer<>());
        http.logout(withDefaults());
        // @formatter:on
        applyDefaultConfigurers(http);
        return http;
    }
}

另外一个地方则是在上面的 SecurityFilterChainConfiguration 配置类中使用 http.build() 构建 SecurityFilterChain 之前（参见上面 defaultSecurityFilterChain 的代码），至此，我们大概理清了所有的 Security Filters 是如何创建的，下面再以表格的形式重新整理下：

其实，如果仔细观察我们的程序输出的日志，也可以看到 Spring Security 默认的过滤器链为 DefaultSecurityFilterChain，以及它注入的所有 Security Filters：

2023-05-17 08:16:18.173  INFO 3936 --- [           main] o.s.s.web.DefaultSecurityFilterChain     : Will secure any request with [
        org.springframework.security.web.session.DisableEncodeUrlFilter@1d6751e3, 
        org.springframework.security.web.context.request.async.WebAsyncManagerIntegrationFilter@2d258eff, 
        org.springframework.security.web.context.SecurityContextPersistenceFilter@202898d7, 
        org.springframework.security.web.header.HeaderWriterFilter@2c26ba07, 
        org.springframework.security.web.csrf.CsrfFilter@52d3fafd, 
        org.springframework.security.web.authentication.logout.LogoutFilter@235c997d, 
        org.springframework.security.web.authentication.UsernamePasswordAuthenticationFilter@5d5c41e5, 
        org.springframework.security.web.authentication.ui.DefaultLoginPageGeneratingFilter@50b93353, 
        org.springframework.security.web.authentication.ui.DefaultLogoutPageGeneratingFilter@6dca31eb, 
        org.springframework.security.web.authentication.www.BasicAuthenticationFilter@22825e1e, 
        org.springframework.security.web.savedrequest.RequestCacheAwareFilter@2c719bd4, 
        org.springframework.security.web.servletapi.SecurityContextHolderAwareRequestFilter@53aa38be, 
        org.springframework.security.web.authentication.AnonymousAuthenticationFilter@4a058df8, 
        org.springframework.security.web.session.SessionManagementFilter@42ea7565, 
        org.springframework.security.web.access.ExceptionTranslationFilter@77cb452c, 
        org.springframework.security.web.access.intercept.FilterSecurityInterceptor@8054fe2]

在某些低版本中，可能会显示 DefaultSecurityFilterChain: Will not secure any request 这样的日志，这可能是 Spring Security 的 BUG，升级到最新版本即可。

其中有几个 Security Filters 比较重要，是实现认证和授权的基础：

• CsrfFilter：默认开启对所有接口的 CSRF 防护，关于 CSRF 的详细信息，可以参考 Configuring CSRF/XSRF with Spring Security；
• DefaultLoginPageGeneratingFilter：用于生成 /login 登录页面；
• DefaultLogoutPageGeneratingFilter：用于生成 /login?logout 登出页面；
• LogoutFilter：当用户退出应用时被调用，它通过注册的 LogoutHandler 删除会话并清理 SecurityContext，然后通过 LogoutSuccessHandler 将页面重定向到 /login?logout；
• UsernamePasswordAuthenticationFilter：实现基于用户名和密码的安全认证，当认证失败，抛出 AuthenticationException 异常；
• BasicAuthenticationFilter：实现 Basic 安全认证，当认证失败，抛出 AuthenticationException 异常；
• AnonymousAuthenticationFilter：如果 SecurityContext 中没有 Authentication 对象时，它自动创建一个匿名用户 anonymousUser，角色为 ROLE_ANONYMOUS；
• FilterSecurityInterceptor：这是 Spring Security 的最后一个 Security Filters，它从 SecurityContext 中获取 Authentication 对象，然后对请求的资源做权限判断，当授权失败，抛出 AccessDeniedException 异常；
• ExceptionTranslationFilter：用于处理过滤器链中抛出的 AuthenticationException 和 AccessDeniedException 异常，AuthenticationException 异常由 AuthenticationEntryPoint 来处理，AccessDeniedException 异常由 AccessDeniedHandler 来处理；

认证和授权

有了 Security Filters，我们就可以实现各种 Spring Security 的相关功能了。应用程序的安全性归根结底包括了两个主要问题：认证（Authentication） 和 授权（Authorization）。认证解决的是 你是谁？ 的问题，而授权负责解决 你被允许做什么？，授权也被称为 访问控制（Access Control）。这一节将深入学习 Spring Security 是如何实现认证和授权的。

跳转到 /login 页面

让我们回到第一节的例子，当访问 /hello 时，可以看到浏览器自动跳转到了 /login 登录页面，那么 Spring Security 是如何实现的呢？为了一探究竟，我们可以将 Spring Security 的日志级别调到 TRACE：

logging.level.org.springframework.security=TRACE

这样我们就能完整地看到这个请求经过 Security Filters 的处理过程：

2023-05-20 09:37:38.558 DEBUG 6632 --- [nio-8080-exec-9] o.s.security.web.FilterChainProxy        : Securing GET /hello
2023-05-20 09:37:38.559 TRACE 6632 --- [nio-8080-exec-9] o.s.security.web.FilterChainProxy        : Invoking DisableEncodeUrlFilter (1/17)
2023-05-20 09:37:38.559 TRACE 6632 --- [nio-8080-exec-9] o.s.security.web.FilterChainProxy        : Invoking WebAsyncManagerIntegrationFilter (2/17)
2023-05-20 09:37:38.560 TRACE 6632 --- [nio-8080-exec-9] o.s.security.web.FilterChainProxy        : Invoking SecurityContextPersistenceFilter (3/17)
2023-05-20 09:37:38.561 TRACE 6632 --- [nio-8080-exec-9] w.c.HttpSessionSecurityContextRepository : No HttpSession currently exists
2023-05-20 09:37:38.561 TRACE 6632 --- [nio-8080-exec-9] w.c.HttpSessionSecurityContextRepository : Created SecurityContextImpl [Null authentication]
2023-05-20 09:37:38.562 DEBUG 6632 --- [nio-8080-exec-9] s.s.w.c.SecurityContextPersistenceFilter : Set SecurityContextHolder to empty SecurityContext
2023-05-20 09:37:38.562 TRACE 6632 --- [nio-8080-exec-9] o.s.security.web.FilterChainProxy        : Invoking HeaderWriterFilter (4/17)
2023-05-20 09:37:38.562 TRACE 6632 --- [nio-8080-exec-9] o.s.security.web.FilterChainProxy        : Invoking CorsFilter (5/17)
2023-05-20 09:37:38.566 TRACE 6632 --- [nio-8080-exec-9] o.s.security.web.FilterChainProxy        : Invoking CsrfFilter (6/17)
2023-05-20 09:37:38.567 TRACE 6632 --- [nio-8080-exec-9] o.s.security.web.csrf.CsrfFilter         : Did not protect against CSRF since request did not match CsrfNotRequired [TRACE, HEAD, GET, OPTIONS]
2023-05-20 09:37:38.568 TRACE 6632 --- [nio-8080-exec-9] o.s.security.web.FilterChainProxy        : Invoking LogoutFilter (7/17)
2023-05-20 09:37:38.571 TRACE 6632 --- [nio-8080-exec-9] o.s.s.w.a.logout.LogoutFilter            : Did not match request to Ant [pattern='/logout', POST]        
2023-05-20 09:37:38.573 TRACE 6632 --- [nio-8080-exec-9] o.s.security.web.FilterChainProxy        : Invoking UsernamePasswordAuthenticationFilter (8/17)
2023-05-20 09:37:38.574 TRACE 6632 --- [nio-8080-exec-9] w.a.UsernamePasswordAuthenticationFilter : Did not match request to Ant [pattern='/login', POST]
2023-05-20 09:37:38.576 TRACE 6632 --- [nio-8080-exec-9] o.s.security.web.FilterChainProxy        : Invoking DefaultLoginPageGeneratingFilter (9/17)
2023-05-20 09:37:38.578 TRACE 6632 --- [nio-8080-exec-9] o.s.security.web.FilterChainProxy        : Invoking DefaultLogoutPageGeneratingFilter (10/17)
2023-05-20 09:37:38.582 TRACE 6632 --- [nio-8080-exec-9] .w.a.u.DefaultLogoutPageGeneratingFilter : Did not render default logout page since request did not match [Ant [pattern='/logout', GET]]
2023-05-20 09:37:38.583 TRACE 6632 --- [nio-8080-exec-9] o.s.security.web.FilterChainProxy        : Invoking BasicAuthenticationFilter (11/17)
2023-05-20 09:37:38.584 TRACE 6632 --- [nio-8080-exec-9] o.s.s.w.a.www.BasicAuthenticationFilter  : Did not process authentication request since failed to find username and password in Basic Authorization header
2023-05-20 09:37:38.587 TRACE 6632 --- [nio-8080-exec-9] o.s.security.web.FilterChainProxy        : Invoking RequestCacheAwareFilter (12/17)
2023-05-20 09:37:38.588 TRACE 6632 --- [nio-8080-exec-9] o.s.s.w.s.HttpSessionRequestCache        : No saved request
2023-05-20 09:37:38.590 TRACE 6632 --- [nio-8080-exec-9] o.s.security.web.FilterChainProxy        : Invoking SecurityContextHolderAwareRequestFilter (13/17)      
2023-05-20 09:37:38.591 TRACE 6632 --- [nio-8080-exec-9] o.s.security.web.FilterChainProxy        : Invoking AnonymousAuthenticationFilter (14/17)
2023-05-20 09:37:38.592 TRACE 6632 --- [nio-8080-exec-9] o.s.s.w.a.AnonymousAuthenticationFilter  : Set SecurityContextHolder to AnonymousAuthenticationToken [Principal=anonymousUser, Credentials=[PROTECTED], Authenticated=true, Details=WebAuthenticationDetails [RemoteIpAddress=127.0.0.1, SessionId=null], Granted Authorities=[ROLE_ANONYMOUS]]
2023-05-20 09:37:38.593 TRACE 6632 --- [nio-8080-exec-9] o.s.security.web.FilterChainProxy        : Invoking SessionManagementFilter (15/17)
2023-05-20 09:37:38.593 TRACE 6632 --- [nio-8080-exec-9] o.s.security.web.FilterChainProxy        : Invoking ExceptionTranslationFilter (16/17)
2023-05-20 09:37:38.594 TRACE 6632 --- [nio-8080-exec-9] o.s.security.web.FilterChainProxy        : Invoking FilterSecurityInterceptor (17/17)
2023-05-20 09:37:38.596 TRACE 6632 --- [nio-8080-exec-9] edFilterInvocationSecurityMetadataSource : Did not match request to EndpointRequestMatcher includes=[health], excludes=[], includeLinks=false - [permitAll] (1/2)
2023-05-20 09:37:38.610 TRACE 6632 --- [nio-8080-exec-9] o.s.s.w.a.i.FilterSecurityInterceptor    : Did not re-authenticate AnonymousAuthenticationToken [Principal=anonymousUser, Credentials=[PROTECTED], Authenticated=true, Details=WebAuthenticationDetails [RemoteIpAddress=127.0.0.1, SessionId=null], Granted Authorities=[ROLE_ANONYMOUS]] before authorizing
2023-05-20 09:37:38.619 TRACE 6632 --- [nio-8080-exec-9] o.s.s.w.a.i.FilterSecurityInterceptor    : Authorizing filter invocation [GET /hello] with attributes [authenticated]
2023-05-20 09:37:38.626 TRACE 6632 --- [nio-8080-exec-9] o.s.s.w.a.expression.WebExpressionVoter  : Voted to deny authorization
2023-05-20 09:37:38.632 TRACE 6632 --- [nio-8080-exec-9] o.s.s.w.a.i.FilterSecurityInterceptor    : Failed to authorize filter invocation [GET /hello] with attributes [authenticated] using AffirmativeBased [DecisionVoters=[org.springframework.security.web.access.expression.WebExpressionVoter@f613067], AllowIfAllAbstainDecisions=false]
2023-05-20 09:37:38.640 TRACE 6632 --- [nio-8080-exec-9] o.s.s.w.a.ExceptionTranslationFilter     : Sending AnonymousAuthenticationToken [Principal=anonymousUser, Credentials=[PROTECTED], Authenticated=true, Details=WebAuthenticationDetails [RemoteIpAddress=127.0.0.1, SessionId=null], Granted Authorities=[ROLE_ANONYMOUS]] 
to authentication entry point since access is denied

org.springframework.security.access.AccessDeniedException: Access is denied
        at org.springframework.security.access.vote.AffirmativeBased.decide(AffirmativeBased.java:73) ~[spring-security-core-5.7.8.jar:5.7.8]

2023-05-20 09:37:38.691 DEBUG 6632 --- [nio-8080-exec-9] o.s.s.w.s.HttpSessionRequestCache        : Saved request http://localhost:8080/hello to session
2023-05-20 09:37:38.693 DEBUG 6632 --- [nio-8080-exec-9] s.w.a.DelegatingAuthenticationEntryPoint : Trying to match using And [Not [RequestHeaderRequestMatcher [expectedHeaderName=X-Requested-With, expectedHeaderValue=XMLHttpRequest]], MediaTypeRequestMatcher [contentNegotiationStrategy=org.springframework.web.accept.HeaderContentNegotiationStrategy@4b95451, matchingMediaTypes=[application/xhtml+xml, image/*, text/html, text/plain], useEquals=false, ignoredMediaTypes=[*/*]]]       
2023-05-20 09:37:38.701 DEBUG 6632 --- [nio-8080-exec-9] s.w.a.DelegatingAuthenticationEntryPoint : Match found! Executing org.springframework.security.web.authentication.LoginUrlAuthenticationEntryPoint@168ad26f
2023-05-20 09:37:38.709 DEBUG 6632 --- [nio-8080-exec-9] o.s.s.web.DefaultRedirectStrategy        : Redirecting to http://localhost:8080/login
2023-05-20 09:37:38.712 TRACE 6632 --- [nio-8080-exec-9] o.s.s.w.header.writers.HstsHeaderWriter  : Not injecting HSTS header since it did not match request to [Is Secure]
2023-05-20 09:37:38.720 DEBUG 6632 --- [nio-8080-exec-9] w.c.HttpSessionSecurityContextRepository : Did not store empty SecurityContext
2023-05-20 09:37:38.730 DEBUG 6632 --- [nio-8080-exec-9] w.c.HttpSessionSecurityContextRepository : Did not store empty SecurityContext
2023-05-20 09:37:38.731 DEBUG 6632 --- [nio-8080-exec-9] s.s.w.c.SecurityContextPersistenceFilter : Cleared SecurityContextHolder to complete request

这个过程中有两点比较重要：第一点是经过 AnonymousAuthenticationFilter 时，将当前用户设置为 anonymousUser，角色为 ROLE_ANONYMOUS；第二点是经过 FilterSecurityInterceptor 时，校验当前用户是否有访问 /hello 页面的权限，在上面的 defaultSecurityFilterChain 中，可以看到 http.authorizeRequests().anyRequest().authenticated() 这样的代码，这说明 Spring Security 默认对所有的页面都开启了鉴权，所以会抛出 AccessDeniedException 异常，而这个异常被 ExceptionTranslationFilter 拦截，并将这个异常交给 LoginUrlAuthenticationEntryPoint 处理，从而重定向到 /login 页面，整个过程的示意图如下：

接下来，浏览器开始访问重定向后的 /login 页面，这时请求又会再一次经历一系列的 Security Filters，和上面的 /hello 请求不一样的是，/login 请求经过 DefaultLoginPageGeneratingFilter 时，会生成上面我们看到的登录页面并结束整个调用链：

public class DefaultLoginPageGeneratingFilter extends GenericFilterBean {

    private void doFilter(HttpServletRequest request, HttpServletResponse response, FilterChain chain)
            throws IOException, ServletException {
        boolean loginError = isErrorPage(request);
        boolean logoutSuccess = isLogoutSuccess(request);
        if (isLoginUrlRequest(request) || loginError || logoutSuccess) {
            String loginPageHtml = generateLoginPageHtml(request, loginError, logoutSuccess);
            response.setContentType("text/html;charset=UTF-8");
            response.setContentLength(loginPageHtml.getBytes(StandardCharsets.UTF_8).length);
            response.getWriter().write(loginPageHtml);
            return;
        }
        chain.doFilter(request, response);
    }
}

AuthenticationManager：剖析认证流程

接下来，输入用户名和密码并提交，请求会再一次经历 Security Filters，这一次，请求在 UsernamePasswordAuthenticationFilter 这里被拦截下来，并开始了用户名和密码的认证过程：

public class UsernamePasswordAuthenticationFilter extends AbstractAuthenticationProcessingFilter {

    @Override
    public Authentication attemptAuthentication(HttpServletRequest request, HttpServletResponse response)
            throws AuthenticationException {
        if (this.postOnly && !request.getMethod().equals("POST")) {
            throw new AuthenticationServiceException("Authentication method not supported: " + request.getMethod());
        }
        String username = obtainUsername(request);
        username = (username != null) ? username.trim() : "";
        String password = obtainPassword(request);
        password = (password != null) ? password : "";
        UsernamePasswordAuthenticationToken authRequest = UsernamePasswordAuthenticationToken.unauthenticated(username,
                password);
        // Allow subclasses to set the "details" property
        setDetails(request, authRequest);
        return this.getAuthenticationManager().authenticate(authRequest);
    }
}

这里将遇到 Spring Security 中处理认证的核心接口：AuthenticationManager：

public interface AuthenticationManager {

    Authentication authenticate(Authentication authentication) throws AuthenticationException;
}

这个接口只有一个 authenticate() 方法，它的入参是一个未认证的 Authentication，从 UsernamePasswordAuthenticationFilter 的代码中可以看到使用了 UsernamePasswordAuthenticationToken，它的返回有三种情况：

• 如果认证成功，则返回认证成功后的 Authentication（通常带有 authenticated=true）；
• 如果认证失败，则抛出 AuthenticationException 异常；
• 如果无法判断，则返回 null；

AuthenticationManager 接口最常用的一个实现是 ProviderManager 类，它包含了一个或多个 AuthenticationProvider 实例：

public class ProviderManager implements AuthenticationManager {

    private List<AuthenticationProvider> providers;
}

AuthenticationProvider 有点像 AuthenticationManager，但它有一个额外的方法 boolean supports(Class<?> authentication)：

public interface AuthenticationProvider {

    Authentication authenticate(Authentication authentication) throws AuthenticationException;

    boolean supports(Class<?> authentication);
}

Spring Security 会遍历列表中所有的 AuthenticationProvider，并通过 supports() 方法来选取合适的 AuthenticationProvider 实例来实现认证，从上文中我们知道，UsernamePasswordAuthenticationFilter 在认证时使用的 Authentication 类型为 UsernamePasswordAuthenticationToken，对于这个 Authentication，默认使用的 AuthenticationProvider 是 DaoAuthenticationProvider，它继承自抽象类 AbstractUserDetailsAuthenticationProvider：

public abstract class AbstractUserDetailsAuthenticationProvider
        implements AuthenticationProvider, InitializingBean, MessageSourceAware {

    @Override
    public Authentication authenticate(Authentication authentication) throws AuthenticationException {

        String username = determineUsername(authentication);
        UserDetails user = retrieveUser(username, (UsernamePasswordAuthenticationToken) authentication);
        
        this.preAuthenticationChecks.check(user);
        additionalAuthenticationChecks(user, (UsernamePasswordAuthenticationToken) authentication);
        this.postAuthenticationChecks.check(user);
        
        Object principalToReturn = user;
        if (this.forcePrincipalAsString) {
            principalToReturn = user.getUsername();
        }
        return createSuccessAuthentication(principalToReturn, authentication, user);
    }
}

其中，最关键的代码有两行，第一行是通过 retrieveUser() 方法获取 UserDetails：

public class DaoAuthenticationProvider extends AbstractUserDetailsAuthenticationProvider {

    @Override
    protected final UserDetails retrieveUser(String username, UsernamePasswordAuthenticationToken authentication)
            throws AuthenticationException {
        
        UserDetails loadedUser = this.getUserDetailsService().loadUserByUsername(username);
        return loadedUser;
    }
}

进入 retrieveUser() 方法内部，可以看到它是通过 UserDetailsService 的 loadUserByUsername() 方法来获取 UserDetails 的，而这个 UserDetailsService 默认实现是 InMemoryUserDetailsManager：

public class InMemoryUserDetailsManager implements UserDetailsManager, UserDetailsPasswordService {

    @Override
    public UserDetails loadUserByUsername(String username) throws UsernameNotFoundException {
        UserDetails user = this.users.get(username.toLowerCase());
        if (user == null) {
            throw new UsernameNotFoundException(username);
        }
        return new User(user.getUsername(), user.getPassword(), user.isEnabled(), user.isAccountNonExpired(),
                user.isCredentialsNonExpired(), user.isAccountNonLocked(), user.getAuthorities());
    }
}

它的实现非常简单，就是从 users 这个 Map 中直接获取 UserDetails，那么 users 这个 Map 又是从哪来的呢？ 答案就是我们在配置文件中配置的 spring.security.user，我们可以从自动配置类 UserDetailsServiceAutoConfiguration 中找到 InMemoryUserDetailsManager 的初始化代码：

public class UserDetailsServiceAutoConfiguration {

    @Bean
    @Lazy
    public InMemoryUserDetailsManager inMemoryUserDetailsManager(SecurityProperties properties,
            ObjectProvider<PasswordEncoder> passwordEncoder) {
        SecurityProperties.User user = properties.getUser();
        List<String> roles = user.getRoles();
        return new InMemoryUserDetailsManager(User.withUsername(user.getName())
            .password(getOrDeducePassword(user, passwordEncoder.getIfAvailable()))
            .roles(StringUtils.toStringArray(roles))
            .build());
    }
}

另一行关键代码是通过 additionalAuthenticationChecks() 方法对 UserDetails 和 UsernamePasswordAuthenticationToken 进行校验，一般来说，就是验证密码是否正确：

public class DaoAuthenticationProvider extends AbstractUserDetailsAuthenticationProvider {

    @Override
    protected void additionalAuthenticationChecks(UserDetails userDetails,
            UsernamePasswordAuthenticationToken authentication) throws AuthenticationException {
        
        String presentedPassword = authentication.getCredentials().toString();
        if (!this.passwordEncoder.matches(presentedPassword, userDetails.getPassword())) {
            this.logger.debug("Failed to authenticate since password does not match stored value");
            throw new BadCredentialsException(this.messages
                    .getMessage("AbstractUserDetailsAuthenticationProvider.badCredentials", "Bad credentials"));
        }
    }
}

一旦用户名和密码都验证通过，就调用 createSuccessAuthentication() 方法创建并返回一个认证成功后的 Authentication，然后经过一系列的后处理，整个认证的流程如下所示：

其中，SecurityContextHolder 将认证成功后的 Authentication 保存到安全上下文中供后续 Filter 使用；AuthenticationSuccessHandler 用于定义一些认证成功后的自定义逻辑，默认实现为 SimpleUrlAuthenticationSuccessHandler，它返回一个重定向，将浏览器转到登录之前用户访问的页面。

在我的测试中，SimpleUrlAuthenticationSuccessHandler 貌似并没有触发，新版本的逻辑有变动？

AccessDecisionManager：剖析授权流程

其实，在上面分析重定向 /login 页面的流程时已经大致了解了实现授权的逻辑，请求经过 FilterSecurityInterceptor 时，校验当前用户是否有访问页面的权限，如果没有，则会抛出 AccessDeniedException 异常。FilterSecurityInterceptor 的核心代码如下：

public class FilterSecurityInterceptor extends AbstractSecurityInterceptor implements Filter {
    
    public void invoke(FilterInvocation filterInvocation) throws IOException, ServletException {

        InterceptorStatusToken token = super.beforeInvocation(filterInvocation);
        try {
            filterInvocation.getChain().doFilter(filterInvocation.getRequest(), filterInvocation.getResponse());
        }
        finally {
            super.finallyInvocation(token);
        }
        super.afterInvocation(token, null);
    }
}

可以看到，主要逻辑就包含在 beforeInvocation()、finallyInvocation() 和 afterInvocation() 这三个方法中，而对授权相关的部分则位于 beforeInvocation() 方法中：

public abstract class AbstractSecurityInterceptor
        implements InitializingBean, ApplicationEventPublisherAware, MessageSourceAware {

    protected InterceptorStatusToken beforeInvocation(Object object) {
        
        Collection<ConfigAttribute> attributes = this.obtainSecurityMetadataSource().getAttributes(object);
        
        Authentication authenticated = authenticateIfRequired();
        
        // Attempt authorization
        attemptAuthorization(object, attributes, authenticated);
        
        if (this.publishAuthorizationSuccess) {
            publishEvent(new AuthorizedEvent(object, attributes, authenticated));
        }

        return new InterceptorStatusToken(SecurityContextHolder.getContext(), false, attributes, object);
    }

    private void attemptAuthorization(Object object, Collection<ConfigAttribute> attributes,
            Authentication authenticated) {
        try {
            this.accessDecisionManager.decide(authenticated, object, attributes);
        }
        catch (AccessDeniedException ex) {
            publishEvent(new AuthorizationFailureEvent(object, attributes, authenticated, ex));
            throw ex;
        }
    }
}

在这里，我们遇到了 Spring Security 实现授权的核心接口：AccessDecisionManager，Spring Security 就是通过该接口的 decide() 方法来决定用户是否有访问某个资源的权限。AccessDecisionManager 接口的默认实现为 AffirmativeBased，可以从 AbstractInterceptUrlConfigurer 中找到它的踪影：

public abstract class AbstractInterceptUrlConfigurer<C extends AbstractInterceptUrlConfigurer<C, H>, H extends HttpSecurityBuilder<H>>
        extends AbstractHttpConfigurer<C, H> {
    
    private AccessDecisionManager createDefaultAccessDecisionManager(H http) {
        AffirmativeBased result = new AffirmativeBased(getDecisionVoters(http));
        return postProcess(result);
    }
}

AffirmativeBased 实例中包含一个或多个 AccessDecisionVoter，它通过遍历所有的 AccessDecisionVoter 依次投票决定授权是否允许，只要有一个 AccessDecisionVoter 拒绝，则抛出 AccessDeniedException 异常：

public class AffirmativeBased extends AbstractAccessDecisionManager {

    @Override
    @SuppressWarnings({ "rawtypes", "unchecked" })
    public void decide(Authentication authentication, Object object, Collection<ConfigAttribute> configAttributes)
            throws AccessDeniedException {
        int deny = 0;
        for (AccessDecisionVoter voter : getDecisionVoters()) {
            int result = voter.vote(authentication, object, configAttributes);
            switch (result) {
            case AccessDecisionVoter.ACCESS_GRANTED:
                return;
            case AccessDecisionVoter.ACCESS_DENIED:
                deny++;
                break;
            default:
                break;
            }
        }
        if (deny > 0) {
            throw new AccessDeniedException(
                    this.messages.getMessage("AbstractAccessDecisionManager.accessDenied", "Access is denied"));
        }
        // To get this far, every AccessDecisionVoter abstained
        checkAllowIfAllAbstainDecisions();
    }
}

默认情况下，AffirmativeBased 实例中只有一个 AccessDecisionVoter，那就是 WebExpressionVoter：

public class WebExpressionVoter implements AccessDecisionVoter<FilterInvocation> {

    @Override
    public int vote(Authentication authentication, FilterInvocation filterInvocation,
            Collection<ConfigAttribute> attributes) {
        
        WebExpressionConfigAttribute webExpressionConfigAttribute = findConfigAttribute(attributes);
        
        EvaluationContext ctx = webExpressionConfigAttribute.postProcess(
                this.expressionHandler.createEvaluationContext(authentication, filterInvocation), filterInvocation);

        boolean granted = ExpressionUtils.evaluateAsBoolean(webExpressionConfigAttribute.getAuthorizeExpression(), ctx);
        if (granted) {
            return ACCESS_GRANTED;
        }
        return ACCESS_DENIED;
    }
}

WebExpressionVoter 将授权转换为 SpEL 表达式，检查授权是否通过，就是看执行 SpEL 表达式的结果是否为 true，这里的细节还有很多，详细内容还是参考 官方文档 吧。

参考

• Spring Security Documentation
• Getting started with Spring Security and Spring Boot
• Spring Security Tutorial 《Spring Security 教程》
• Spring Security 从入门到进阶
• Spring Security 认证流程
• Spring Security 鉴权流程

更多

Spring Security 的安全防护

• Protection Against Exploits
• Configuring CSRF/XSRF with Spring Security
• Configuring CORS with Spring Boot and Spring Security

Spring Security 自定义配置

• Java Configuration
• A Custom Spring SecurityConfigurer

Spring Security 单元测试

• Testing

RPC 又被称为 远程过程调用，英文全称为 Remote Procedure Call，是一种服务间的通信规范，它可以让你像调用本地方法一样调用远程服务提供的方法，而不需要关心底层的通信细节。RPC 的概念早在上个世纪七八十年代就已经被提出，1984 年，Birrell 和 Nelson 在 ACM Transactions on Computer Systems 期刊上发表了一篇关于 RPC 的经典论文 Implementing remote procedure calls，论文中首次给出了实现 RPC 的基本框架：

从这个框架中可以看到很多现代 RPC 框架的影子，比如客户端和服务端的 Stub、序列化和反序列化等，事实上，所有后来的 RPC 框架几乎都是源自于这个原型。

不过在那个年代，RPC 的争议是非常大的，由于网络环境的不可靠性，RPC 永远都不可能做到像调用本地方法一样。大家提出了一堆问题，比如：故障恢复、请求重试、异步请求、服务寻址等，在那个互联网都还没有出现的年代，一堆大神们就已经在讨论分布式系统间的调用问题了，而他们讨论的问题焦点，基本上都演变成了 RPC 历史中永恒的话题。

为了解决这些问题，软件架构经历了一代又一代的发展和演进。1988 年，Sun 公司推出了第一个商业化的 RPC 库 Sun RPC ，并被定义为标准的 RPC 规范；1991 年，非营利性组织 OMG 发布 CORBA，它通过接口定义语言 IDL 中的抽象类型映射让异构环境之间的互操作成为了可能；不过由于其复杂性，很快就被微软推出的基于 XML 的 SOAP 技术所打败，随后 SOAP 作为 W3C 标准大大推动了 Web Service 概念的发展；像 SOAP 这种基于 XML 的 RPC 技术被称为 XML-RPC，它最大的问题是 XML 报文内容过于冗余，对 XML 的解析效率也很低，于是 JSON 应运而生，进而导致 RESTful 的盛行；不过无论是 XML 还是 JSON，都是基于文本传输，性能都无法让人满意，直到 2008 年，Google 开源 Protocol Buffers，这是一种高效的结构化数据存储格式，可以用于结构化数据的序列化，非常适合做数据存储或 RPC 数据交换格式；可能是由于微服务的流行，之后的 RPC 框架如雨后春笋般蓬勃发展，同年，Facebook 向 Apache 贡献了开源项目 Thrift，2009 年，Hadoop 之父 Doug Cutting 开发出 Avro，成为 Hadoop 的一个子项目，随后又脱离 Hadoop 成为 Apache 顶级项目；2011 年，阿里也开源了它自研的 RPC 框架 Dubbo，和前两个一样，最后也贡献给了 Apache；2015 年，Google 开源 gRPC 框架，开创性地使用 HTTP/2 作为传输协议，基于 HTTP/2 的多路复用和服务端推送技术，gRPC 支持双向流式通信，这使得 RPC 框架终于不再拘泥于万年不变的 C/S 模型了。

2017 年，gRPC 作为孵化项目成为 CNCF 的一员，不论是 Envoy 还是 Istio 等 Service Mesh 方案，都将 gRPC 作为一等公民，可以预见的是，谷歌正在将 gRPC 打造成云原生时代通信层事实上的标准。

从 Hello World 开始

这一节我们使用 Go 语言实现一个简单的 Hello World 服务，学习 gRPC 的基本概念。首先，我们通过 go mod init 初始化示例项目：

$ mkdir demo && cd demo
$ go mod init example.com/demo
go: creating new go.mod: module example.com/demo
go: to add module requirements and sums:
        go mod tidy

然后获取 grpc 依赖：

$ go get google.golang.org/grpc@latest
go: downloading golang.org/x/net v0.5.0
go: downloading golang.org/x/sys v0.4.0
go: downloading google.golang.org/genproto v0.0.0-20230110181048-76db0878b65f
go: downloading golang.org/x/text v0.6.0
go: added github.com/golang/protobuf v1.5.2
go: added golang.org/x/net v0.5.0
go: added golang.org/x/sys v0.4.0
go: added golang.org/x/text v0.6.0
go: added google.golang.org/genproto v0.0.0-20230110181048-76db0878b65f
go: added google.golang.org/grpc v1.53.0
go: added google.golang.org/protobuf v1.28.1

编写 .proto 文件

正如前文所述，Google 在 2009 年开源了一种高效的结构化数据存储格式 Protocol Buffers，这种格式非常适合用于 RPC 的数据交换，所以顺理成章的，Google 在开发 gRPC 时就采用了 Protocol Buffers 作为默认的数据格式。不过要注意的是 Protocol Buffers 不仅仅是一种数据格式，而且也是一种 IDL（Interface Description Language，接口描述语言），它通过一种中立的方式来描述接口和数据类型，从而实现跨语言和跨平台开发。

一般使用 .proto 后缀的文件来定义接口和数据类型，所以接下来，我们要创建一个 hello.proto 文件，我们将其放在 proto 目录下：

$ mkdir proto && cd proto
$ vim hello.proto

文件内容如下：

syntax = "proto3";

option go_package = "example.com/demo/proto";

service HelloService {
  rpc SayHello (HelloRequest) returns (HelloResponse) {}
}

message HelloRequest {
  string name = 1;
}

message HelloResponse {
  string message = 1;
}

我们在第一行指定使用 proto3 语法，这是目前推荐的版本，如果不指定，默认将使用 proto2，可能会导致一些版本兼容性的问题。随后我们用关键字 service 定义了一个 HelloService 服务，该服务包含一个 SayHello 方法，方法的入参为 HelloRequest，出参为 HelloResponse，这两个消息类型都在后面通过关键字 message 所定义。Protocol Buffers 的语法非常直观，也比较容易理解，这里只是使用了一些简单的语法，其他更复杂的语法可以参考 Protocol Buffers 的官方文档，另外这里有一份 中文语法指南 也可供参考。

编写好 hello.proto 文件之后，我们还需要一些工具将其转换为 Go 语言。这些工具包括：

• protoc
• protoc-gen-go
• protoc-gen-go-grpc

protoc 是 Protocol Buffers 编译器，用于将 .proto 文件转换为其他编程语言，而不同语言的转换工作由不同语言的插件来实现。Go 语言的插件有两个：protoc-gen-go 和 protoc-gen-go-grpc，插件 protoc-gen-go 会生成一个后缀为 .pb.go 的文件，其中包含 .proto 文件中定义数据类型和其序列化方法；插件 protoc-gen-go-grpc 会生成一个后缀为 _grpc.pb.go 的文件，其中包含供客户端调用的服务方法和服务端要实现的接口类型。

protoc 可以从 Protocol Buffers 的 Release 页面 下载，下载后将 bin 目录添加到 PATH 环境变量即可：

$ curl -LO https://github.com/protocolbuffers/protobuf/releases/download/v22.0/protoc-22.0-linux-x86_64.zip

protoc-gen-go 和 protoc-gen-go-grpc 两个插件可以通过 go install 命令直接安装：

$ go install google.golang.org/protobuf/cmd/protoc-gen-go@v1.28.1
$ go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@v1.2.0

安装完成后使用 --version 参数检测各个命令是否正常：

$ protoc --version
libprotoc 22.0

$ protoc-gen-go --version
protoc-gen-go v1.28.1

$ protoc-gen-go-grpc --version
protoc-gen-go-grpc 1.2.0

一切就绪后，就可以使用下面这行命令生成相应的 Go 代码了：

$ cd proto
$ protoc --go_out=. --go_opt=paths=source_relative \
    --go-grpc_out=. --go-grpc_opt=paths=source_relative \
    hello.proto

这个命令在当前目录下生成了 hello.pb.go 和 hello_grpc.pb.go 两个文件。

实现服务端

在生成的 hello_grpc.pb.go 文件中，定义了一个 HelloServiceServer 接口：

// HelloServiceServer is the server API for HelloService service.
// All implementations must embed UnimplementedHelloServiceServer
// for forward compatibility
type HelloServiceServer interface {
    SayHello(context.Context, *HelloRequest) (*HelloResponse, error)
    mustEmbedUnimplementedHelloServiceServer()
}

并且在接口的下面提供了一个默认实现：

type UnimplementedHelloServiceServer struct {
}

func (UnimplementedHelloServiceServer) SayHello(context.Context, *HelloRequest) (*HelloResponse, error) {
    return nil, status.Errorf(codes.Unimplemented, "method SayHello not implemented")
}
func (UnimplementedHelloServiceServer) mustEmbedUnimplementedHelloServiceServer() {}

注意看 HelloServiceServer 的上面有一行注释：All implementations must embed UnimplementedHelloServiceServer for forward compatibility，为了保证向前兼容性，我们自己在实现这个接口时必须要嵌入 UnimplementedHelloServiceServer 这个默认实现，这篇文章 对此有一个简单的说明。

接下来我们创建一个 server 目录，并创建一个 main.go 文件：

$ mkdir server && cd server
$ vim main.go

定义 server 结构体，继承 UnimplementedHelloServiceServer 并重写 SayHello 方法：

type server struct {
    proto.UnimplementedHelloServiceServer
}

func (s *server) SayHello(ctx context.Context, request *proto.HelloRequest) (*proto.HelloResponse, error) {
    log.Printf("Request recieved: %v\n", request.GetName())
    return &proto.HelloResponse{
        Message: "Hello " + request.GetName(),
    }, nil
}

然后在入口方法中，通过 proto.RegisterHelloServiceServer(s, &server{}) 将我们的实现注册到 grpc Server 中：

func main() {

    lis, err := net.Listen("tcp", ":8080")
    if err != nil {
        log.Fatalf("Server listen failed!")
    }
    log.Printf("Server listening at: %s", lis.Addr())

    s := grpc.NewServer()
    proto.RegisterHelloServiceServer(s, &server{})
    if err := s.Serve(lis); err != nil {
        log.Fatalf("Server serve failed!")
    }
}

使用 go run 运行该代码：

$ go run ./server/main.go
2023/03/02 07:40:50 Server listening at: [::]:8080

一个 gRPC 的服务端就启动成功了！

实现客户端

接下来，我们来实现客户端。其实，在 hello_grpc.pb.go 文件中，protoc 也为我们定义了一个 HelloServiceClient 接口：

type HelloServiceClient interface {
    SayHello(ctx context.Context, in *HelloRequest, opts ...grpc.CallOption) (*HelloResponse, error)
}

并提供了该接口的默认实现：

type helloServiceClient struct {
    cc grpc.ClientConnInterface
}

func NewHelloServiceClient(cc grpc.ClientConnInterface) HelloServiceClient {
    return &helloServiceClient{cc}
}

func (c *helloServiceClient) SayHello(ctx context.Context, in *HelloRequest, opts ...grpc.CallOption) (*HelloResponse, error) {
    out := new(HelloResponse)
    err := c.cc.Invoke(ctx, "/HelloService/SayHello", in, out, opts...)
    if err != nil {
        return nil, err
    }
    return out, nil
}

和 HelloServiceServer 不同的是，这个客户端实现我们无需修改，可以直接使用。首先我们创建一个 client 目录，并创建一个 main.go 文件：

$ mkdir client && cd client
$ vim main.go

然后在入口方法中，通过 grpc.Dial 创建一个和服务端的连接：

conn, err := grpc.Dial("localhost:8080", grpc.WithTransportCredentials(insecure.NewCredentials()))
if err != nil {
    log.Fatalf("Connect grpc server failed: %v", err)
}
defer conn.Close()

注意我们的服务端没有开启 TLS，连接是不安全的，所以我们需要加一个不安全证书的连接选项，否则连接的时候会报错：

Connect grpc server failed: grpc: no transport security set (use grpc.WithTransportCredentials(insecure.NewCredentials()) explicitly or set credentials)

然后使用 hello_grpc.pb.go 文件中提供的 NewHelloServiceClient 方法创建一个客户端实例：

c := proto.NewHelloServiceClient(conn)

同时使用 context 创建一个带超时的上下文：

ctx, cancel := context.WithTimeout(context.Background(), time.Second)
defer cancel()

使用创建的客户端调用 SayHello 方法：

r, err := c.SayHello(ctx, &proto.HelloRequest{Name: "zhangsan"})
if err != nil {
    log.Fatalf("Call SayHello failed: %v", err)
}
log.Printf("SayHello response: %s", r.GetMessage())

从调用的代码上看起来，确实和调用本地方法一样，传入 HelloRequest 请求，得到 HelloResponse 响应。至此，一个简单的客户端就编写完成了，使用 go run 运行该代码：

$ go run ./client/main.go
2023/03/03 07:03:34 SayHello response: Hello zhangsan

测试服务端

除了编写客户端，我们也可以使用其他的工具来测试服务端，对于 HTTP 服务，我们一般使用 curl 或 Postman 之类的工具；而对于 gRPC 服务，也有类似的工具，比如 grpcurl 或 grpcui 等，这里整理了一份 关于 gRPC 工具的清单。

这里使用 grpcurl 来对我们的服务端进行简单的测试。首先从它的 Release 页面 下载并安装 grpcurl：

$ curl -LO https://github.com/fullstorydev/grpcurl/releases/download/v1.8.7/grpcurl_1.8.7_linux_x86_64.tar.gz

grpcurl 中最常使用的是 list 子命令，它可以列出服务端支持的所有服务：

$ grpcurl -plaintext localhost:8080 list
Failed to list services: server does not support the reflection API

不过这要求我们的服务端必须开启 反射 API，打开 server/main.go 文件，在其中加上下面这行代码：

reflection.Register(s)

这样我们就通过 Go 语言中提供的 reflection 包开启了反射 API，然后使用 grpcurl 的 list 命令重新列出服务端的所有服务：

$ grpcurl -plaintext localhost:8080 list
HelloService
grpc.reflection.v1alpha.ServerReflection

如果服务端没有开启反射 API，grpc 也支持直接使用 Proto 文件 或 Protoset 文件。

我们还可以使用 list 命令继续列出 HelloService 服务的所有方法：

$ grpcurl -plaintext localhost:8080 list HelloService
HelloService.SayHello

如果要查看某个方法的详细信息，可以使用 describe 命令：

$ grpcurl -plaintext localhost:8080 describe HelloService.SayHello
HelloService.SayHello is a method:
rpc SayHello ( .HelloRequest ) returns ( .HelloResponse );

可以看出，这和我们在 proto 文件中的定义是一致的。最后，使用 grpcurl 来调用这个方法：

$ grpcurl -plaintext -d '{"name": "zhangsan"}' localhost:8080 HelloService.SayHello
{
  "message": "Hello zhangsan"
}

如果入参比较大，可以将其保存在一个文件中，使用下面的方法来调用：

$ cat input.json | grpcurl -plaintext -d @ localhost:8080 HelloService.SayHello
{
  "message": "Hello zhangsan"
}

gRPC 的四种形式

gRPC 支持四种不同的通信方式：

• 简单 RPC（Simple RPC）
• 服务端流 RPC（Server-side streaming RPC）
• 客户端流 RPC（Client-side streaming RPC）
• 双向流 RPC（Bidirectional streaming RPC）

上一节中的 SayHello 就是一个简单 RPC 的例子：

rpc SayHello (HelloRequest) returns (HelloResponse) {}

这种 RPC 有时候也被称为 Unary RPC，除此之外，gRPC 还支持三种流式通信方法，也即 Streaming RPC。

服务端流 RPC（Server-side streaming RPC）

第一种叫服务端流 RPC，它接受一个正常的请求，并以流的形式向客户端发送多个响应。在下面的例子中，客户端向服务端发送一个字符串，服务端对字符串进行分词，并将分词结果以流式返回给客户端。首先，我们在 .proto 文件中定义 Split 方法和相应的消息体：

rpc Split (SplitRequest) returns (stream SplitResponse) {}

然后，使用 protoc 生成服务端和客户端的代码，接着在 server/main.go 文件中添加服务端实现：

func (s *server) Split(request *proto.SplitRequest, stream proto.HelloService_SplitServer) error {
    log.Printf("Request recieved: %v\n", request.GetSentence())
    words := strings.Split(request.GetSentence(), " ")
    for _, word := range words {
        if err := stream.Send(&proto.SplitResponse{Word: word}); err != nil {
            return err
        }
    }
    return nil
}

和简单 RPC 的 SayHello 方法相比，服务端流 RPC 的 Split 方法在参数上有一些细微的差别，少了一个 ctx context.Context 参数，而多了一个 stream proto.HelloService_SplitServer 参数，这是 protoc 自动生成的一个接口：

type HelloService_SplitServer interface {
    Send(*SplitResponse) error
    grpc.ServerStream
}

这个接口继承自 grpc.ServerStream 接口，并具有一个 Send 方法，用来向客户端发送响应。

在 client/main.go 文件中添加客户端实现：

stream, err := c.Split(ctx, &proto.SplitRequest{Sentence: "Hello World"})
if err != nil {
    log.Fatalf("Call Split failed: %v", err)
}
for {
    r, err := stream.Recv()
    if err == io.EOF {
        break
    }
    if err != nil {
        log.Fatalf("%v.Split(_) = _, %v", c, err)
    }
    log.Printf("Split response: %s", r.GetWord())
}

和简单 RPC 的客户端代码相比，Split 方法不是直接返回 SplitResponse，而是返回一个 stream 流，它的类型为 HelloService_SplitClient 接口：

type HelloService_SplitClient interface {
    Recv() (*SplitResponse, error)
    grpc.ClientStream
}

这个接口继承自 grpc.ClientStream 接口，并具有一个 Recv 方法，用来接受服务端发送的响应，当服务端发送结束后，Recv 方法将返回 io.EOF 错误。

客户端流 RPC（Client-side streaming RPC）

第二种叫客户端流 RPC，它以流的形式接受客户端发送来的多个请求，服务端处理之后返回一个正常的响应。在下面的例子中，客户端向服务端发送多个数字，服务端收集之后进行求和，并将求和结果返回给客户端。首先，我们在 .proto 文件中定义 Sum 方法和相应的消息体：

rpc Sum (stream SumRequest) returns (SumResponse) {}

然后，使用 protoc 生成服务端和客户端的代码，接着在 server/main.go 文件中添加服务端实现：

func (s *server) Sum(stream proto.HelloService_SumServer) error {
    var sum int32 = 0
    for {
        r, err := stream.Recv()
        if err == io.EOF {
            return stream.SendAndClose(&proto.SumResponse{Sum: sum})
        }
        if err != nil {
            return err
        }
        sum = sum + r.GetNum()
    }
}

从上面的代码可以看到，Sum 方法没有了 request 参数，只有一个 stream 参数，请求参数通过 stream.Recv 以流的形式读取，当读取结束后，stream.Recv 方法将返回 io.EOF 错误，这时我们通过 stream.SendAndClose 将处理之后的结果返回给客户端，并关闭连接。

在 client/main.go 文件中添加客户端实现：

stream2, err := c.Sum(ctx)
if err != nil {
    log.Fatalf("%v.Sum(_) = _, %v", c, err)
}
nums := []int32{1, 2, 3, 4, 5, 6, 7}
for _, num := range nums {
    if err := stream2.Send(&proto.SumRequest{Num: num}); err != nil {
        log.Fatalf("%v.Send(%v) = %v", stream, num, err)
    }
}
response, err := stream2.CloseAndRecv()
if err != nil {
    log.Fatalf("%v.CloseAndRecv() failed: %v", stream2, err)
}
log.Printf("Sum response: %v", response.GetSum())

在上面的代码中，Sum 方法返回一个 stream 变量，然后通过 stream.Send 不断向服务端发送请求，当数据发送结束后，再通过 stream.CloseAndRecv 关闭连接，并接受服务端响应。

双向流 RPC（Bidirectional streaming RPC）

第三种叫双向流 RPC，这有点像网络聊天，服务端和客户端双方以任意的顺序互相通信，服务端可以在每次接受客户端请求时就返回一次响应，也可以接受多个请求后再返回一次响应。首先，我们在 .proto 文件中定义 Chat 方法和相应的消息体：

rpc Chat (stream ChatRequest) returns (stream ChatResponse) {}

然后，使用 protoc 生成服务端和客户端的代码，接着在 server/main.go 文件中添加服务端实现：

func (s *server) Chat(stream proto.HelloService_ChatServer) error {
    for {
        r, err := stream.Recv()
        if err == io.EOF {
            return nil
        }
        if err != nil {
            return err
        }
        if err = stream.Send(&proto.ChatResponse{Message: "Reply to " + r.GetMessage()}); err != nil {
            return err
        }
    }
}

上面的代码和客户端流 RPC 比较类似，只不过服务端的响应变得更及时，每次接受到客户端请求时都会响应，而不是等客户端请求结束后再响应。

在 client/main.go 文件中添加客户端实现：

stream3, err := c.Chat(ctx)
if err != nil {
    log.Fatalf("%v.Chat(_) = _, %v", c, err)
}
waitc := make(chan struct{})
go func() {
    for {
        in, err := stream3.Recv()
        if err == io.EOF {
            close(waitc)
            return
        }
        if err != nil {
            log.Fatalf("Failed to receive: %v", err)
        }
        log.Printf("Chat response: %s", in.GetMessage())
    }
}()

messages := []string{"Hello", "How're you?", "Bye"}
for _, message := range messages {
    if err := stream3.Send(&proto.ChatRequest{Message: message}); err != nil {
        log.Fatalf("Failed to send: %v", err)
    }
}
stream3.CloseSend()
<-waitc

双向流 RPC 的客户端实现要稍微复杂一点。首先，我们通过 stream.Send 来发送请求，由于发送和接受都是流式的，所以我们没法像客户端流 RPC 那样通过 stream.CloseAndRecv() 来获取响应，我们只能调用 stream.CloseSend() 告诉服务端发送结束，然后我们需要创建一个新的 goroutine 来接受响应，另外，我们创建了一个 channel，用于在响应接受结束后通知主线程，以便程序能正常退出。

参考

• gRPC 官方文档
• gRPC 官方文档中文版
• Awesome gRPC
• gRPC教程
• Protocol Buffers V3中文语法指南(翻译)
• 那些年，我们追过的RPC
• RPC 发展史
• GRPC简介
• 怎么看待谷歌的开源 RPC 框架 gRPC？
• grpcurl工具 - Go语言高级编程

更多

gRPC 安全认证

根据官方的 gRPC 认证指南，gRPC 支持多种不同的认证方法，包括：SSL/TLS 认证、ALTS 认证 以及一些基于 token 的认证方法，如 OAuth2、GCE 等。

除了这些原生的认证方法，我们也可以通过 Metadata 来传送认证信息，从而实现 gRPC 的认证功能；另外，gRPC 还支持拦截器特性，通过拦截器也可以实现安全认证，Go gRPC Middleware 提供了很多拦截器的例子。

WebAssembly（简称 WASM）是一种以安全有效的方式运行可移植程序的新兴 Web 技术，下面是引用 MDN 上对它的定义：

WebAssembly 是一种新的编码方式，可以在现代的网络浏览器中运行 － 它是一种低级的类汇编语言，具有紧凑的二进制格式，可以接近原生的性能运行，并为诸如 C/C++ 等语言提供一个编译目标，以便它们可以在 Web 上运行。它也被设计为可以与 JavaScript 共存，允许两者一起工作。

也就是说，无论你使用的是哪一种语言，我们都可以将其转换为 WebAssembly 格式，并在浏览器中以原生的性能运行。WebAssembly 的开发团队来自 Mozilla、Google、Microsoft 和 Apple，分别代表着四大网络浏览器 Firefox、Chrome、Microsoft Edge 和 Safari，从 2017 年 11 月开始，这四大浏览器就开始实验性的支持 WebAssembly。当时 WebAssembly 还没有形成标准，这么多的浏览器开发商对某个尚未标准化的技术 达成如此一致的意见，这在历史上是很罕见的，可以看出这绝对是一项值得关注的技术，被号称为 the future of web development。

WebAssembly 在 2019 年 12 月 5 日被万维网联盟（W3C）推荐为标准，与 HTML，CSS 和 JavaScript 一起，成为 Web 的第四种语言。

WebAssembly 之前的历史

JavaScript 诞生于 1995 年 5 月，一个让人津津乐道的故事是，当时刚加入网景的 Brendan Eich 仅仅花了十天时间就开发出了 JavaScript 语言。开发 JavaScript 的初衷是为 HTML 提供一种脚本语言使得网页变得更动态，当时根本就没有考虑什么浏览器兼容性、安全性、移植性这些东西，对性能也没有特别的要求。但随着 Web 技术的发展，网页要解决的问题已经远不止简单的文本信息，而是包括了更多的高性能图像处理和 3D 渲染等方面，这时，JavaScript 的性能问题就凸显出来了。于是，如何让 JavaScript 执行的更快，变成了各大浏览器生产商争相竞逐的目标。

浏览器性能之战

这场关于浏览器的性能之战在 2008 年由 Google 带头打响，这一年的 9 月 2 日，Google 发布了一款跨时代的浏览器 Chrome，具备简洁的用户界面和极致的用户体验，内置的 V8 引擎采用了全新的 JIT 编译（Just-in-time compilation，即时编译）技术，使得浏览器的响应速度得到了几倍的提升。次年，Apple 发布了他们的浏览器新版本 Safari 4，其中引入新的 Nitro 引擎（也被称为 SquirrelFish 或 JavaScriptCore），同样使用的是 JIT 技术。紧接着，Mozilla 在 Firefox 3.5 中引入 TraceMonkey 技术，Microsoft 在 2011 年也推出 Chakra) 引擎。

使用 JIT 技术，极大的提高了 JavaScript 的性能。那么 JIT 是如何工作的呢？我们知道，JavaScript 是解释型语言，因此传统的 JavaScript 引擎需要逐行读取 JavaScript 代码，并将其翻译成可执行的机器码。很显然这是极其低效的，如果有一段代码需要执行上千次，那么 JavaScript 引擎也会傻傻的翻译上千次。JIT 技术的基本思路就是缓存，它将执行频次比较高的代码实时编译成机器码，并缓存起来，当下次执行到同样代码时直接使用相应的机器码替换掉，从而获得极大的性能提升。另外，对于执行频次非常高的代码，JIT 引擎还会使用优化编译器（Optimising Compiler）编译出更高效的机器码。关于 JIT 技术的原理可以参考 A crash course in just-in-time (JIT) compilers 这篇文章。

JIT 技术推出之后，JavaScript 的性能得到了飞速提升：

随着性能的提升，JavaScript 的应用范围也得到了极大的扩展，Web 内容变得更加丰富，图片、视频、游戏，等等等等，甚至有人将 JavaScript 用于后端开发（Node.js）。不过 JIT 也不完全是 “性能银弹”，因为通过 JIT 优化也是有一定代价的，比如存储优化后的机器码需要更多的内存，另外 JIT 优化对变量类型非常敏感，但是由于 JavaScript 动态类型 的特性，用户代码中对某个变量的类型并不会严格固定，这时 JIT 优化的效果将被大打折扣。比如下面这段简单的代码：

function arraySum(arr) {
  var sum = 0;
  for (var i = 0; i < arr.length; i++) {
    sum += arr[i];
  }
}

假设 JIT 检测到 sum += arr[i]; 这行代码被执行了很多次，开始对其进行编译优化，它首先需要确认 sum、arr、i 和 arr[i] 这些变量的类型，如果 arr[i] 是 int 类型，这就是整数相加的操作，但如果 arr[i] 是 string 类型，这又变成了字符串拼接的操作，这两种情况编译成的机器码是完全不同的。所以 JIT 引擎会先根据代码执行情况假设变量为某种类型，然后再进行优化，当执行时会对类型进行检测，一旦检测到类型不同时，这个 JIT 优化将被作废，这个过程叫做 去优化（deoptimization，或者 bailing out）。假如用户写出这样的代码：

arr = [1, "hello"];

JavaScript 这种动态类型的特点对 JIT 引擎是非常不友好的，反复的优化和去优化不仅无法提高性能，甚至会有副作用。所以在实际的生产环境中，JIT 的效果往往没有那么显著，通过 JIT 的优化很快就遇到了瓶颈。

但是日益丰富的 Web 内容对 JavaScript 的性能提出了更高的要求，尤其是 3D 游戏，这些游戏在 PC 上跑都很吃力，更别说在浏览器里运行了。如何让 JavaScript 执行地更快，是摆在各大浏览器生产商面前的一大难题，很快，Google 和 Mozilla 交出了各自的答卷。

Google 的 NaCl 解决方案

Google 在 2008 年开源了 NaCl 技术，并在 2011 年的 Chrome 14 中正式启用。NaCl 的全称为 Native Client，这是一种可以在浏览器中执行原生代码（native code）的技术，听起来很像是 Microsoft 当时所使用的 ActiveX 技术，不过 ActiveX 由于其安全性一直被人所诟病。而 NaCl 定义了一套原生代码的安全子集，执行于独立的沙盒环境之中，并通过一套被称为 PPAPI（Pepper Plugin API）的接口来和 JavaScript 交互，避免了可能的安全问题。NaCl 采取了和 JIT 截然不同的 AOT 编译（Ahead-of-time compilation，即提前编译）技术，所以在性能上的表现非常突出，几乎达到了和原生应用一样的性能。不过由于 NaCl 应用是 C/C++ 语言编写的，与 CPU 架构强关联，不具有可移植性，因此需要针对不同的平台进行开发以及编译，用户使用起来非常痛苦。

为了解决这个问题，Google 在 2013 年又推出了 PNaCl 技术（Portable Native Client），PNaCl 的创新之处在于使用 LLVM IR（Intermediate Representation）来分发应用，而不是直接分发原生代码，LLVM IR 也被称为 Bitcode，它是一种平台无关的中间语言表示，实现了和 Java 一样的目标：一次编译，到处运行。

如果我们站在今天的视角来看，PNaCl 这项技术是非常超前的，它的核心理念和如今的 WebAssembly 如出一辙，只不过它出现的时机不对，当时很多人都对在浏览器中执行原生代码持怀疑态度，担心可能出现和 ActiveX 一样的安全问题，而且当时 HTML5 技术正发展的如火如荼，人们都在想着如何从浏览器中移除诸如 Flash 或 Java Applet 这些 JavaScript 之外的技术，所以 PNaCl 技术从诞生以来，一直不温不火，尽管后来 Firefox 和 Opera 等浏览器也开始支持 NaCl 和 PPAPI，但是一直无法得到普及（当时的 IE 还占领着浏览器市场的半壁江山）。

随着 WebAssembly 技术的发展，Google Chrome 最终在 2018 年移除了对 PNaCl 的支持，决定全面拥抱 WebAssembly 技术。

Mozilla 的 asm.js 解决方案

2010 年，刚刚加入 Mozilla 的 Alon Zakai 在工作之余突发奇想，能不能将自己编写的 C/C++ 游戏引擎运行在浏览器上？当时 NaCl 技术还没怎么普及，Alon Zakai 一时之间并没有找到什么好的技术方案。好在 C/C++ 是强类型语言，JavaScript 是弱类型语言，所以将 C/C++ 代码转换为 JavaScript 在技术上是完全可行的。Alon Zakai 于是便开始着手编写这样的一个编译器，Emscripten 便由此诞生了！

Emscripten 和传统的编译器很类似，都是将某种语言转换为另一种语言形式，不过他们之间有着本质的区别。传统的编译器是将一种语言编译成某种 low-level 的语言，比如将 C/C++ 代码编译成二进制文件（机器码），这种编译器被称为 Compiler；而 Emscripten 是将 C/C++ 代码编译成和它 same-level 的 JavaScript 代码，这种编译器被称为 Transpiler 或者 Source to source compiler。

Emscripten 相比于 NaCl 来说兼容性更好，于是很快就得到了 Mozilla 的认可。之后 Alon Zakai 被邀请加入 Mozilla 的研究团队并全职负责 Emscripten 的开发，以及通过 Emscripten 编译生成的 JavaScript 代码的性能优化上。在 2013 年，Alon Zakai 联合 Luke Wagner，David Herman 一起发布了 asm.js 规范，同年，Mozilla 也发布了 Firefox 22，并内置了新一代的 OdinMonkey 引擎，它是第一个支持 asm.js 规范的 JavaScript 引擎。

asm.js 的思想很简单，就是尽可能的在 JavaScript 中使用类型明确的参数，并通过 TypedArray 取消了垃圾回收机制，这样可以让 JIT 充分利用和优化，进而提高 JavaScript 的执行性能。比如下面这样一段 C 代码：

int f(int i) {
  return i + 1;
}

使用 Emscripten 编译生成的 JavaScript 代码如下：

function f(i) {
  i = i|0;
  return (i + 1)|0;
}

通过在变量和返回值后面加上 |0 这样的操作，我们明确了参数和返回值的数据类型，当 JIT 引擎检测到这样的代码时，便可以跳过语法分析和类型推断这些步骤，将代码直接转成机器语言。据称，使用 asm.js 能达到原生代码 50% 左右的速度，虽然没有 NaCl 亮眼，但是这相比于普通的 JavaScript 代码而言已经是极大的性能提升了。而且我们可以看出 asm.js 采取了和 NaCl 截然不同的思路，asm.js 其实和 JavaScript 没有区别，它只是 JavaScript 的一个子集而已，这样做不仅可以充分发挥出 JIT 的最大功效，而且能兼容所有的浏览器。

但是 asm.js 也存在着不少的问题。首先由于它还是和 JavaScript一样是文本格式，因此加载和解析都会花费比较长的时间，这被称为慢启动问题；其次，asm.js 除了在变量后面加 |0 之外，还有很多类似这样的标注代码：

很显然，这让代码的可读性和可扩展性都变的很差；最后，仍然是性能问题，通过 asm.js 无论怎么优化最终生成的都还是 JavaScript 代码，性能自然远远比不上原生代码；因此这并不是一个非常理想的技术方案。

其他解决方案

除了 NaCl 和 asm.js，实际上还有一些其他的解决方案，但最终的结果要么夭折，要么被迫转型。其中值得一提的是 Google 发明的 Dart 语言，Dart 语言的野心很大，它最初的目的是要取代 JavaScript 成为 Web 的首选语言，为此 Google 还开发了一款新的浏览器 Dartium，内置 Dart 引擎可以执行 Dart 程序，而且对于不支持 Dart 程序的浏览器，它还提供了相应的工具将 Dart 转换为 JavaScript。这一套组合拳可谓是行云流水，可是结果如何可想而知，不仅很难得到用户的承认，而且也没得到其他浏览器的认可，最终 Google 在 2015 年取消了该计划。目前 Dart 语言转战移动开发领域，比如跨平台开发框架 Flutter 就是采用 Dart 开发的。

WebAssembly = NaCl + asm.js

随着技术的发展，Mozilla 和 Google 的工程师出现了很多次的交流和合作，通过汲取 NaCl 和 asm.js 两者的优点，双方推出了一种全新的技术方案：

• 和 NaCl/PNaCl 一样，基于二进制格式，从而能够被快速解析，达到原生代码的运行速度；
• 和 PNaCl 一样，依赖于通用的 LLVM IR，这样既具备可移植性，又便于其他语言快速接入；
• 和 asm.js 一样，使用 Emscripten 等工具链进行编译；另外，Emscripten 同时支持生成 asm.js 和二进制格式，当浏览器不兼容新的二进制格式时，asm.js 可以作为降级方案；
• 和 asm.js 一样，必须以非常自然的方式直接操作 Web API，而不用像 PNaCl 一样需要处理与 JavaScript 之间的通信；

这个技术方案在 2015 年正式命名为 WebAssembly，2017 年各大浏览器生产商纷纷宣布支持 WebAssembly，2019 年 WebAssembly 正式成为 W3C 标准，一场关于浏览器的性能革命已经悄然展开。

WebAssembly 入门示例

从上面的学习中我们知道，WebAssembly 是一种通用的编码格式，并且已经有很多编程语言支持将源码编译成这种格式了，官方的 Getting Started 有一个详细的列表。这一节我们就跟着官方的教程实践一下下面这三种语言：

• C/C++
• Rust
• Go

将 C/C++ 程序编译成 WebAssembly

首先我们参考 Emscripten 的官方文档 上的步骤下载并安装 Emscripten SDK，安装完成后通过下面的命令检查环境是否正常：

$ emcc --check
emcc (Emscripten gcc/clang-like replacement + linker emulating GNU ld) 3.1.24 (68a9f990429e0bcfb63b1cde68bad792554350a5)
shared:INFO: (Emscripten: Running sanity checks)

环境准备就绪后，我们就可以将 C/C++ 的代码编译为 WebAssembly 了。写一个简单的 Hello World 程序 hello.c：

#include <stdio.h>

int main() {
    printf("Hello World\n");
    return 0;
}

然后使用 emcc 进行编译：

$ emcc hello.c -o hello.html

上面这个命令会生成三个文件：

• hello.wasm - 这就是生成的 WebAssembly 二进制字节码文件
• hello.js - 包含一段胶水代码（glue code）通过 JavaScript 来调用 WebAssembly 文件
• hello.html - 方便开发调试，在页面上显示 WebAssembly 的调用结果

我们不能直接用浏览器打开 hello.html 文件，因为浏览器不支持 file:// 形式的 XHR 请求，所以在 HTML 中无法加载 .wasm 等相关的文件，为了看到效果，我们需要一个 Web Server，比如 Nginx、Tomcat 等，不过这些安装和配置都比较麻烦，我们还有很多其他的方法快速启动一个 Web Server。

比如通过 npm 启动一个本地 Web Server：

$ npx serve .

或者使用 Python3 的 http.server 模块：

$ python3 -m http.server

访问 hello.html 页面如下：

可以看到我们在 C 语言中打印的 Hello World 成功输出到浏览器了。

另外，我们也可以将 C 语言中的函数暴露出来给 JavaScript 调用。默认情况下，Emscripten 生成的代码只会调用 main() 函数，其他函数忽略。我们可以使用 emscripten.h 中的 EMSCRIPTEN_KEEPALIVE 来暴露函数，新建一个 greet.c 文件如下：

#include <stdio.h>
#include <emscripten/emscripten.h>

int main() {
    printf("Hello World\n");
    return 0;
}

#ifdef __cplusplus
#define EXTERN extern "C"
#else
#define EXTERN
#endif

EXTERN EMSCRIPTEN_KEEPALIVE void greet(char* name) {
    printf("Hello, %s!\n", name);
}

上面的代码定义了一个 void greet(char* name) 函数，为了让这个函数可以在 JavaScript 中调用，编译时还需要指定 NO_EXIT_RUNTIME 和 EXPORTED_RUNTIME_METHODS 参数，将 ccall 导出来：

$ emcc -o greet.html greet.c -s NO_EXIT_RUNTIME=1 -s EXPORTED_RUNTIME_METHODS=ccall

greet.html 文件和上面的 hello.html 几乎是一样的，我们在该文件中加几行代码来测试我们的 greet() 函数，首先加一个按钮：

<button id="mybutton">Click me!</button>

然后为它添加点击事件，可以看到 JavaScript 就是通过上面导出的 ccall 来调用 greet() 函数的：

document.getElementById("mybutton").addEventListener("click", () => {
  const result = Module.ccall(
    "greet",         // name of C function
    null,            // return type
    ["string"],      // argument types
    ["WebAssembly"]  // arguments
  );
});

除了 ccall，我们还可以使用 -s EXPORTED_RUNTIME_METHODS=ccall,cwrap 同时导出 ccall 和 cwrap 函数。ccall 的作用是直接调用某个 C 函数，而 cwrap 是将 C 函数编译为一个 JavaScript 函数，并可以反复调用，这在正式项目中更实用。

点击这个按钮，可以在页面和控制台上都看到 greet() 函数打印的内容：

将 Rust 程序编译成 WebAssembly

首先按照官方文档 安装 Rust，安装包含了一系列常用的命令行工具，包括 rustup、rustc、cargo 等，其中 cargo 是 Rust 的包管理器，可以使用它安装 wasm-pack：

$ cargo install wasm-pack

wasm-pack 用于将 Rust 代码编译成 WebAssembly 格式，不过要注意它不支持 bin 项目，只支持 lib 项目，所以我们通过 --lib 来创建项目：

$ cargo new --lib rust-demo
     Created library `rust-demo` package

打开 ./src/lib.rs，输入以下代码：

use wasm_bindgen::prelude::*;

#[wasm_bindgen]
extern {
    pub fn alert(s: &str);
}

#[wasm_bindgen]
pub fn greet(name: &str) {
    alert(&format!("Hello, {}!", name));
}

在上面的代码中我们使用了 wasm-bindgen 这个工具，它实现了 JavaScript 和 Rust 之间的相互通信，关于它的详细说明可以参考 《The wasm-bindgen Guide》 这本电子书。我们首先通过 extern 声明了一个 JavaScript 中的 alert() 函数，然后我们就可以像调用正常的 Rust 函数一样调用这个外部函数。下面再通过 pub fn 将 greet() 函数暴露出来，这样我们也可以从 JavaScript 中调用这个 Rust 函数。

接着修改 ./Cargo.toml 文件，添加如下内容：

[lib]
crate-type = ["cdylib"]

[dependencies]
wasm-bindgen = "0.2"

其中 crate-type = ["cdylib"] 表示生成一个 动态系统库。使用 wasm-pack 进行构建：

$ wasm-pack build --target web

这个命令会生成一个 pkg 目录，里面包含了 wasm 文件和对应的 JavaScript 胶水代码，这和上面的 emcc 结果类似，不过并没有生成相应的测试 HTML 文件。我们手工创建一个 index.html 文件，内容如下：

<!DOCTYPE html>
<html lang="en-US">
  <head>
    <meta charset="utf-8" />
    <title>hello-wasm example</title>
  </head>
  <body>
    <script type="module">
      import init, { greet } from "./pkg/rust_demo.js";
      init().then(() => {
        greet("WebAssembly");
      });
    </script>
  </body>
</html>

然后启动一个 Web Server，并在浏览器中打开测试页面：

我们成功在浏览器中调用了使用 Rust 编写的 greet() 函数！

将 Go 程序编译成 WebAssembly

首先确保你已经 安装了 Go：

$ go version
go version go1.19 linux/amd64

使用 go mod init 初始化模块：

$ mkdir go-demo && cd go-demo
$ go mod init com.example

新建一个 main.go 文件：

package main

import "fmt"

func main() {
    fmt.Println("Hello, WebAssembly!")
}

使用 go build 可以将它编译成可执行文件，通过在命令之前指定 GOOS=js GOARCH=wasm 可以将它编译成 WebAssembly 文件：

$ GOOS=js GOARCH=wasm go build -o main.wasm

和上面的 C 语言或 Rust 语言的例子一样，为了测试这个 main.wasm 文件，我们还需要 JavaScript 胶水代码和一个测试 HTML 文件。Go 的安装目录下自带了一个 wasm_exec.js 文件，我们将其拷贝到当前目录：

$ cp "$(go env GOROOT)/misc/wasm/wasm_exec.js" .

然后创建一个 index.html 文件（也可以直接使用 Go 自带的 wasm_exec.html 文件）：

<html>
  <head>
    <meta charset="utf-8"/>
      <script src="wasm_exec.js"></script>
      <script>
        const go = new Go();
        WebAssembly.instantiateStreaming(fetch("main.wasm"), go.importObject).then((result) => {
          go.run(result.instance);
        });
      </script>
  </head>
  <body></body>
</html>

启动 Web Server 后在浏览器中打开该页面：

在控制台中我们就可以看到程序运行的结果了。

除了在浏览器中测试 WebAssembly 文件，也可以使用 Go 安装目录自带的 go_js_wasm_exec 工具来运行它：

$ $(go env GOROOT)/misc/wasm/go_js_wasm_exec ./main.wasm
Hello, WebAssembly!

或者 go run 时带上 -exec 参数来运行：

$ GOOS=js GOARCH=wasm go run -exec="$(go env GOROOT)/misc/wasm/go_js_wasm_exec" .
Hello, WebAssembly!

运行这个命令需要安装 Node.js v12 以上的版本，打开 go_js_wasm_exec 文件可以看到它实际上就是执行 node wasm_exec_node.js 这个命令。

上面的例子是直接在 JavaScript 中执行 Go 程序，如果我们需要将 Go 中的函数导出给 JavaScript 调用，可以通过 syscall/js 来实现：

package main

import (
    "syscall/js"
)

func addFunction(this js.Value, p []js.Value) interface{} {
    sum := p[0].Int() + p[1].Int()
    return js.ValueOf(sum)
}

func main() {
    js.Global().Set("add", js.FuncOf(addFunction))
    select {} // block the main thread forever
}

注意在 main() 函数中我们使用 select {} 将程序阻塞住，防止程序退出，否则 JavaScript 在调用 Go 函数时会报下面这样的错误：

wasm_exec.js:536 Uncaught Error: Go program has already exited
    at globalThis.Go._resume (wasm_exec.js:536:11)
    at wasm_exec.js:549:8
    at <anonymous>:1:1

由于 add 函数是直接添加到 js.Global() 中的，我们可以直接通过 window.add 来访问它：

js.Global() 为我们提供了一个 Go 和 JavaScript 之间的桥梁，我们不仅可以将 Go 函数暴露给 JavaScript 调用，甚至可以通过 js.Global() 来操作 DOM：

func hello(this js.Value, args []js.Value) interface{} {
    doc := js.Global().Get("document")
    h1 := doc.Call("createElement", "h1")
    h1.Set("innerText", "Hello World")
    doc.Get("body").Call("append", h1)
    return nil
}

除了官方的 go build 可以将 Go 程序编译成 WebAssembly 文件，你也可以尝试使用 TinyGo，这是 Go 语言的一个子集实现，它对 Go 规范做了适当的裁剪，只保留了一些比较重要的库，这让它成为了一种更加强大和高效的语言，你可以在意想不到的地方运行它（比如很多物联网设备）。另外，使用 TinyGo 编译 WebAssembly 还有一个很大的优势，它编译出来的文件比 Go 官方编译出来的文件小得多（上面的例子中 C/C++ 或 Rust 编译出来的 wasm 文件只有 100~200K，而 Go 编译出来的 wasm 文件竟然有 2M 多）。

WebAssembly 文本格式

上面我们使用了三种不同的编程语言来体验 WebAssembly，学习了如何编译，以及如何在浏览器中使用 JavaScript 调用它。不过这里有一个问题，由于 wasm 文件是二进制格式，对我们来说是完全黑盒的，不像 JavaScript 是纯文本的，我们可以方便地通过浏览器自带的开发者工具对其进行调试，而 wasm 如果调用出问题，我们将很难排查。实际上，WebAssembly 在设计之初就已经考虑了这样的问题，所以它不仅具有 二进制格式，而且还有一种类似于汇编语言的 文本格式，方便用户查看、编辑和调试。

下面是 WebAssembly 文本格式的一个简单例子：

(module
  (func $add (param $lhs i32) (param $rhs i32) (result i32)
    local.get $lhs
    local.get $rhs
    i32.add)
  (export "add" (func $add))
)

WebAssembly 代码中的基本单元是一个模块，每个模块通过一个大的 S-表达式 来表示，S-表达式是一种嵌套结构，实际上它是树的一种表示形式。上面的代码首先通过 (module) 定义了一个模块，然后模块中使用 (func $add (param $lhs i32) (param $rhs i32) (result i32)) 定义了一个 add() 函数，这个 S-表达式转换为比较好理解的形式就是 i32 add(i32 lhs, i32 rhs)，最后通过 (export "add" (func $add)) 将该函数暴露出来，关于这段代码的详细解释可以参考 Mozilla 官方文档中的 Understanding WebAssembly text format。

我们将上面的代码保存到 add.wat 文件中，并通过 WABT 工具包（The WebAssembly Binary Toolkit）中的 wat2wasm 将其转换为 wasm 格式：

$ wat2wasm add.wat -o add.wasm

使用下面的 JavaScript 脚本加载 wasm 并调用 add() 函数：

fetchAndInstantiate('add.wasm').then(function(instance) {
    console.log(instance.exports.add(1, 2));  // "3"
});

// fetchAndInstantiate() found in wasm-utils.js
function fetchAndInstantiate(url, importObject) {
    return fetch(url).then(response =>
    response.arrayBuffer()
    ).then(bytes =>
    WebAssembly.instantiate(bytes, importObject)
    ).then(results =>
    results.instance
    );
}

将这段 JavaScript 脚本放在一个 HTML 文件中，然后启动 Web Server 访问，可以看到控制台输出了 3，也就是 add(1, 2) 的结果，并且我们还可以通过 Chrome 提供的 开发者工具对 wasm 文件进行调试：

参考

1. WebAssembly 官网
2. WebAssembly | MDN
3. WebAssembly 中文网
4. WebAssembly Design Documents
5. WebAssembly Specification
6. WebAssembly - 维基百科
7. asm.js 和 Emscripten 入门教程
8. 浏览器是如何工作的：Chrome V8 让你更懂JavaScript
9. WebAssembly完全入门——了解wasm的前世今身
10. 浅谈WebAssembly历史
11. A cartoon intro to WebAssembly Articles
12. 一个白学家眼里的 WebAssembly
13. 使用 Docker 和 Golang 快速上手 WebAssembly
14. 如何评论浏览器最新的 WebAssembly 字节码技术？
15. 如何看待 WebAssembly 这门技术？
16. 系统学习WebAssembly（1） —— 理论篇
17. 快 11K Star 的 WebAssembly，你应该这样学
18. WebAssembly 与 JIT
19. WebAssembly 初步探索
20. WebAssembly 實戰 – 讓 Go 與 JS 在瀏覽器上共舞

更多

在非浏览器下运行 WebAssembly

WebAssembly 最早只应用于 Web 浏览器中，但鉴于它所拥有 可移植、安全及高效 等特性，WebAssembly 也被逐渐应用在 Web 领域之外的一些其他场景中，并为此提出了一项新的接口标准 —— WASI（WebAssembly System Interface）。

要让 WebAssembly 跑在非 Web 环境下，我们必须有一款支持 WASI 接口的运行时（WASI runtime），目前比较流行的有：wasttime、wasmer 和 WasmEdge 等，这些运行时提供了不同编程语言的 SDK，可以使得我们在各种不同的语言中调用 WebAssembly 模块。

使用 WABT 工具包

WABT 工具包中除了上文所使用的 wat2wasm 之外，还提供了很多其他有用的工具：

• wat2wasm - 将 WebAssembly 文本格式（.wat）转换为二进制格式（.wasm）
• wasm2wat - 将 WebAssembly 二进制格式（.wasm）转换为文本格式（.wat）
• wasm-objdump - 打印 wasm 文件的信息，类似于 objdump
• wasm-interp - 解码并运行一个 wasm 文件
• wasm-decompile - 将 wasm 文件反编译成一种和 C 语言类似的语法，便于阅读
• wat-desugar
• wasm2c - 将 wasm 文件转换为 C 文件
• wasm-strip
• wasm-validate
• wast2json
• wasm-opcodecnt
• spectest-interp

Java 编程语言发展迅速，从 Java 9 开始，Java 采取了小步迭代的发布方式，以每 6 个月发布一个版本的速度在持续更新，目前最新的版本已经升到 19 了：

尽管如此，据 JRebel 2022 年发布的 Java 开发者生产力报告 显示，Java 8 作为第一个 LTS 版本（另两个是 Java 11 和 17），仍然是使用最多的一个版本。

Java 8 由 Oracle 公司于 2014 年 3 月 18 日发布，在这个版本中新增了大量的特性，首次引入了 Lambda 表达式和方法引用，开启了 Java 语言函数式编程的大门，其中新增的 Stream API（java.util.stream）特性更是将函数式编程发挥到了淋漓尽致的地步。

Stream API 概述

在 Java 8 之前，处理集合数据的常规方法是 for 循环：

List<String> words = List.of("A", "B", "C");
for (String word: words) {
    System.out.println(word.toLowerCase());
}

或者使用 iterator 迭代器：

List<String> words = List.of("A", "B", "C");
Iterator<String> iterator = words.iterator();
while (iterator.hasNext()) {
    System.out.println(iterator.next().toLowerCase());
}

这种集合的遍历方式被称为 外部迭代，也就是说由用户来决定 “做什么”（大写转小写） 和 “怎么做”（通过 for 或 iterator 遍历）。

而在 Java 8 中，新增的 Stream API 通过 内部迭代 来处理集合数据，使用了 访问者设计模式（Visitor Pattern），用户只需要通过函数式的方法提供 “做什么” 即可，“怎么做” 交给 Stream API 内部实现：

List<String> words = List.of("A", "B", "C");
words.stream().forEach(word -> System.out.println(word.toLowerCase()));

使用内部迭代可以让用户更聚焦待解决的问题，编写代码不易出错，而且通常编写的代码更少也更易读。这是 Stream API 的一大特征。其实，上面的两种代码实际上对应着两种截然不同的编程风格，那种用户需要关注怎么做，需要 step-by-step 地告诉计算机执行细节的编程风格，被称为 命令式编程（Imperative programming），而用户只关注做什么，只需要告诉计算机想要什么结果，计算过程由计算机自己决定的编程风格，被称为 声明式编程（Declarative programming）。

另外，正如 Stream API 的名字一样，Stream API 中有很多方法都会返回流对象本身，于是我们就可以将多个操作串联起来形成一个管道（pipeline），写出下面这样流式风格（fluent style）的代码：

List<String> names = students.stream()
    .filter(s -> s.getScore() >= 60)
    .sorted((x, y) -> x.getScore() - y.getScore())
    .map(Student::getName)
    .collect(Collectors.toList());

Stream API 使用

流的创建

JDK 中提供了很多途径来创建一个流，这一节总结一些常用的创建流的方法。流有一个很重要的特性：不会对数据源进行修改，所以我们可以对同一个数据源创建多个流。

创建一个空流

我们可以通过 Stream.empty() 创建一个不包含任何数据的空流：

Stream<String> streamEmpty = Stream.empty();

在代码中使用空指针是一种不好的编程风格，空流的作用就是为了避免在程序中返回空指针：

public Stream<String> streamOf(List<String> list) {
    return list == null || list.isEmpty() ? Stream.empty() : list.stream();
}

从集合类创建流

JDK 中自带了大量的集合类，比如 List、Set 和 Queue 以及它们的子类，这些类都继承自 Collection 接口：

注意 Map 不是集合类，但是 Map 中的 keySet()、values() 和 entrySet() 方法返回的是集合类。

我们可以通过任何一个集合类的 stream() 方法创建一个流：

List<String> collection = Arrays.asList("a", "b", "c");
Stream<String> streamOfCollection = collection.stream();

从数组创建流

数组和集合类都是用于存储多个对象，只不过数组的长度固定，而集合的长度可变。我们可以使用 Arrays.stream() 静态方法从一个数组创建流：

String[] array = new String[]{"a", "b", "c"};
Stream<String> streamOfArray = Arrays.stream(array);

也可以使用 Stream.of() 方法来创建：

Stream<String> streamOfArray2 = Stream.of(array);

由于 Stream.of() 函数的入参定义是一个可变参数，本质上是个数组，所以既可以像上面那样传入一个数组，也可以直接传入数组元素创建：

Stream<String> streamOfArray3 = Stream.of("a", "b", "c");

使用 Stream.builder() 手工创建流

有时候流中的数据不是来自某个数据源，而是需要手工添加，我们可以使用 Stream.builder() 方法手工创建流：

Stream<String> streamOfBuilder = Stream.<String>builder()
    .add("a")
    .add("b")
    .add("c")
    .build();

也可以往 builder 中依次添加：

Stream.Builder<String> builder = Stream.<String>builder();
builder.add("a");
builder.add("b");
builder.add("c");
Stream<String> streamOfBuilder2 = builder.build();

使用 Stream.generate() 生成流

Stream.generate() 方法也可以用于手工创建流，这个方法需要提供一个 Supplier<T> 的实现，生成的是一个无限流，一般通过 limit 来限定数量：

Stream<String> streamOfGenerate = Stream.generate(() -> "hello").limit(3);

上面的例子中通过 Lambda 表达式 () -> "hello" 一直生成 hello 字符串。如果要生成不一样的数据，可以将变量传到 Lambda 表达式中，比如下面的例子生成 1 2 3 这样的连续整数：

AtomicInteger num = new AtomicInteger(0);
Stream<Integer> streamOfGenerate2 = Stream.generate(() -> num.incrementAndGet()).limit(3);

使用 Stream.iterate() 生成流

在上面的例子中，我们通过将变量传到 Lambda 表达式来生成一个整数数列，像这种根据迭代来生成数据的场景，还有一种更简单的实现：

Stream<Integer> streamOfIterate = Stream.iterate(1, n -> n + 1).limit(3);

iterate() 函数第一个参数为流的第一个元素，后续的元素通过第二个参数中的 UnaryOperator<T> 来迭代生成。

生成基础类型的流

由于 Stream<T> 接口使用了泛型，它的类型参数只能是对象类型，所以我们无法生成基础类型的流，我们只能使用相应的封装类型来生成流，这样就会导致自动装箱和拆箱（auto-boxing），影响性能。

于是 JDK 提供了几个特殊的接口来方便我们创建基础类型的流。JDK 一共有 8 个基础类型，包括 4 个整数类型（byte、short、int、long），2 个浮点类型（float、double），1 个字符型（char）和 1 个布尔型（boolean），不过只提供了 3 个基础类型的流：IntStream、LongStream 和 DoubleStream。

基础类型流和普通流接口基本一致，我们可以通过上面介绍的各种方法来创建基础类型流。JDK 还针对不同的基础类型提供了相应的更便捷的生成流的方法，比如 IntStream.range() 函数用于方便的生成某个范围内的整数序列：

IntStream intStream = IntStream.range(1, 4);

要注意的是这个数列是左闭右开的，不包含第二个参数，IntStream.rangeClosed() 函数生成的数列是左右都是闭区间：

IntStream intStream2 = IntStream.rangeClosed(1, 3);

此外，Random 类也提供了一些生成基础类型流的方法，比如下面的代码生成 3 个随机的 int 型整数：

IntStream intStream = new Random().ints(3);

生成随机的 long 和 double 类型：

LongStream longStream = new Random().longs(3);
DoubleStream doubleStream = new Random().doubles(3);

使用 String.chars() 生成字符流

String 类提供了一个 chars() 方法，用于从字符串生成字符流，正如上面所说，JDK 只提供了 IntStream、LongStream 和 DoubleStream 三种基础类型流，并没有 CharStream 一说，所以返回值使用了 IntStream：

IntStream charStream = "abc".chars();

使用 Pattern.splitAsStream() 生成字符串流

我们知道，String 类里有一个 split() 方法可以将一个字符串分割成子串，但是返回值是一个数组，如果要生成一个子串流，可以使用正则表达式包中 Pattern 类的 splitAsStream() 方法：

Stream<String> stringStream = Pattern.compile(", ").splitAsStream("a, b, c");

从文件生成字符串流

另外，Java NIO 包中的 Files 类提供了一个 lines() 方法，它依次读取文件的每一行并生成字符串流：

try (Stream<String> stringStream = Files.lines(Paths.get(filePath + "test.txt"));) {
    stringStream.forEach(System.out::println);
}

注意使用 try-with-resources 关闭文件。

中间操作

上一节主要介绍了一些常用的创建流的方法，流一旦创建好了，就可以对流执行各种操作。我们将对流的操作分成两种类型：中间操作（Intermediate operation） 和 结束操作（Terminal operation），所有的中间操作返回的结果都是流本身，所以可以写出链式的代码，而结束操作会关闭流，让流无法再访问。

中间操作又可以分成 无状态操作（Stateless operation） 和 有状态操作（Stateful operation） 两种，无状态是指元素的处理不受前面元素的影响，而有状态是指必须等到所有元素处理之后才知道最终结果。

下面通过一些实例来演示不同操作的具体用法，首先创建一个流，包含一些学生数据：

Stream<Student> students = Stream.of(
    Student.builder().name("张三").gender("男").age(27).number(3L).interests("画画、篮球").build(),
    Student.builder().name("李四").gender("男").age(29).number(2L).interests("篮球、足球").build(),
    Student.builder().name("王二").gender("女").age(27).number(1L).interests("唱歌、跳舞、画画").build(),
    Student.builder().name("麻子").gender("女").age(31).number(4L).interests("篮球、羽毛球").build()
);

无状态操作

filter

filter 用于对数据流进行过滤，它接受一个 Predicate<? super T> predicate 参数，返回符合该 Predicate 条件的元素：

students = students.filter(s -> s.getAge() > 30);

map / mapToInt / mapToLong / mapToDouble

map 接受一个 Function<? super T, ? extends R> mapper 类型的参数，对数据流的类型进行转换，从 T 类型转换为 R 类型，比如下面的代码将数据流 Stream<Student> 转换为 Stream<StudentDTO>：

Stream<StudentDTO> studentDTOs = students.map(s -> {
    return StudentDTO.builder().name(s.getName()).age(s.getAge()).build();
});

如果要转换成基本类型流，可以使用 mapToInt、mapToLong 或 mapToDouble 方法：

LongStream studentAges = students.mapToLong(s -> s.getAge());

上面的 Lambda 也可以写成方法引用：

LongStream studentAges2 = students.mapToLong(Student::getAge);

flatMap / flatMapToInt / flatMapToLong / flatMapToDouble

flatMap 接受一个 Function<? super T, ? extends Stream<? extends R>> mapper 类型的参数，和 map 不同的是，他将 T 类型转换为 R 类型的流，而不是转换为 R 类型，然后再将流中所有数据平铺得到最后的结果：

Stream<String> studentInterests = students.flatMap(s -> Arrays.stream(s.getInterests().split("、")));

每个学生可能有一个或多个兴趣，使用 、 分割，上面的代码首先将每个学生的兴趣拆开得到一个字符串流，然后将流中的元素平铺，最后得到汇总后的字符串流，该流中包含了所有学生的所有兴趣（元素可能重复）。可以看出 flatMap 实际上是对多个流的数据进行合并。

peek

peek 一般用来调试，它接受一个 Consumer<? super T> action 参数，可以在流的计算过程中对元素进行处理，无返回结果，比如打印出元素的状态：

Stream<String> studentNames = students.filter(s -> s.getAge() > 20)
    .peek(System.out::println)
    .map(Student::getName)
    .peek(System.out::println);

unordered

相遇顺序（encounter order） 是流中的元素被处理时的顺序，创建流的数据源决定了流是否有序，比如 List 或数组是有序的，而 HashSet 是无序的。一些中间操作也可以修改流的相遇顺序，比如 sorted() 用于将无序流转换为有序，而 unordered() 也可以将一个有序流变成无序。

对于 串行流（sequential streams），相遇顺序并不会影响性能，只会影响确定性。如果一个流是有序的，每次执行都会得到相同的结果，如果一个流是无序的，则可能会得到不同的结果。

不过根据官方文档的说法，我使用 unordered() 将一个流改成无序流，重复执行得到的结果还是一样的 [2, 4, 6]，并没有得到不同的结果：

List<Integer> ints = Stream.of(1, 2, 3).unordered()
   .map(x -> x*2)
   .collect(Collectors.toList());

网上有说法 认为，这是因为 unordered() 并不会打乱流原本的顺序，只会 消除流必须保持有序的约束，从而允许后续操作使用不必考虑排序的优化。

对于 并行流（parallel streams），去掉有序约束后可能会提高流的执行效率，有些聚合操作，比如 distinct() 或 Collectors.groupingBy() 在不考虑元素有序时具备更好的性能。

有状态操作

distinct

distinct() 方法用于去除流中的重复元素：

Stream<Integer> intStream = Stream.of(1, 2, 3, 2, 4, 3, 1, 2);
intStream = intStream.distinct();

distinct() 是根据流中每个元素的 equals() 方法来去重的，所以如果流中是对象类型，可能需要重写其 equals() 方法。

sorted

sorted() 方法根据 自然序（natural order） 对流中的元素进行排序，流中的元素必须实现 Comparable 接口：

Stream<Integer> intStream = Stream.of(1, 3, 2, 4);
intStream = intStream.sorted();

如果流中的元素没有实现 Comparable 接口，我们可以提供一个比较器 Comparator<? super T> comparator 对流进行排序：

students = students.sorted(new Comparator<Student>() {

    @Override
    public int compare(Student o1, Student o2) {
        return o1.getAge().compareTo(o2.getAge());
    }
    
});

上面是通过匿名内部类的方式创建了一个比较器，我们可以使用 Lambda 来简化它的写法：

students = students.sorted((o1, o2) -> o1.getAge().compareTo(o2.getAge()));

另外，Comparator 还内置了一些静态方法可以进一步简化代码：

students = students.sorted(Comparator.comparing(Student::getAge));

甚至可以组合多个比较条件写出更复杂的排序逻辑：

students = students.sorted(
    Comparator.comparing(Student::getAge).thenComparing(Student::getNumber)
);

skip / limit

skip 和 limit 这两个方法有点类似于 SQL 中的 LIMIT offset, rows 语句，用于返回指定的记录条数，最常见的一个用处是用来做分页查询。

Stream<Integer> intStream = Stream.of(1, 2, 3, 4, 5, 6, 7, 8, 9, 10);
intStream = intStream.skip(3).limit(3);

dropWhile / takeWhile

dropWhile 和 takeWhile 这两个方法的作用也是返回指定的记录条数，只不过条数不是固定的，而是根据某个条件来决定返回哪些元素：

Stream<Integer> intStream = Stream.of(1, 2, 3, 4, 5, 6, 7, 8, 9, 10);
intStream = intStream.dropWhile(x -> x <= 3).takeWhile(x -> x <= 6);

结束操作

流的中间操作其实只是一个标记，它是延迟执行的，要等到结束操作时才会触发实际的计算，而且每个流只能有一个结束操作。结束操作会关闭流，对已经关闭的流再执行操作会抛出 IllegalStateException 异常。

结束操作也可以分成两种类型：短路操作（Short-Circuit operation） 和 非短路操作（Non-Short-Circuit operation），短路操作是指不用处理全部元素就可以返回结果，它必须一个元素处理一次，而非短路操作可以批量处理数据，但是需要等全部元素都处理完才会返回结果。

短路操作

anyMatch / allMatch / nonMatch

这几个 match 方法非常类似，它们都接受一个 Predicate<? super T> predicate 条件，用于判断流中元素是否满足某个条件。

anyMatch 表示只要有一个元素满足条件即返回 true：

boolean hasAgeGreaterThan30 = students.anyMatch(s -> s.getAge() > 30);

allMatch 表示所有元素都满足条件才返回 true：

boolean allAgeGreaterThan20 = students.allMatch(s -> s.getAge() > 20);

noneMatch 表示所有元素都不满足条件才返回 true：

boolean noAgeGreaterThan40 = students.noneMatch(s -> s.getAge() > 40);

findFirst / findAny

这两个 find 方法也是非常类似，都是从流中返回一个元素，如果没有，则返回一个空的 Optional，它们经常和 filter 方法联合使用。

findFirst 用于返回流中第一个元素：

// 返回的是 李四
Optional<Student> student = students.filter(s -> s.getAge() > 28).findFirst();

而 findAny() 返回的元素是不确定的，如果是串行流，返回的是第一个元素：

// 返回的是 李四
Optional<Student> student = students.filter(s -> s.getAge() > 28).findAny();

如果是并行流，则返回值是随机的：

// 返回不确定
Optional<Student> student = students.parallel().filter(s -> s.getAge() > 28).findAny();

非短路操作

forEach / forEachOrdered

这两个 forEach 方法有点类似于 peek 方法，都是接受一个 Consumer<? super T> action 参数，对流中每一个元素进行处理，只不过 forEach 是结束操作，而 peek 是中间操作。

intStream.forEach(System.out::println);

这两个方法的区别在于 forEach 的处理顺序是不确定的，而 forEachOrdered 会按照流中元素的 相遇顺序（encounter order） 来处理。比如下面的代码：

intStream.parallel().forEach(System.out::println);

由于这里使用了并行流，forEach 输出结果是随机的。如果换成 forEachOrdered，则会保证输出结果是有序的：

intStream.parallel().forEachOrdered(System.out::println);

toArray

toArray 方法用于将流转换为一个数组，默认情况下数组类型是 Object[]：

Object[] array = students.toArray();

如果要转换为确切的对象类型，toArray 还接受一个 IntFunction<A[]> generator 参数，也是数组的构造函数：

Student[] array = students.toArray(Student[]::new);

reduce

在英语中 reduce 这个单词的意思是 “减少、缩小”，顾名思义，reduce 方法的作用也是如此，它会根据某种规则依次处理流中的元素，经过计算与合并后返回一个唯一的值。早在 2004 年，Google 就研究并提出了一种面向大规模数据处理的并行计算模型和方法，被称为 MapReduce，这里的 Map 表示 映射，Reduce 表示 规约，它们和 Java Stream API 中的 map 和 reduce 方法有着异曲同工之妙，都是从函数式编程语言中借鉴的思想。

reduce 方法有三种不同的函数形式，第一种也是最简单的：

Optional<T> reduce(BinaryOperator<T> accumulator);

它接受一个 BinaryOperator<T> accumulator 参数，BinaryOperator 是一个函数式接口，它是 BiFunction 接口的特殊形式，BiFunction 表示的是两个入参和一个出参的函数：

@FunctionalInterface
public interface BiFunction<T, U, R> {
    // ...
}

BinaryOperator 同样也是两个入参和一个出参的函数，但是它的两个入参的类型和出参的类型是一样的：

@FunctionalInterface
public interface BinaryOperator<T> extends BiFunction<T,T,T> {
    // ...
}

accumulator 的意思是累加器，它是一个函数，它有两个参数。它的第一个参数是上次函数执行的返回值（也称为中间结果），第二个参数是流中的元素，函数将两个值按照方法进行处理，得到值赋给下次执行这个函数的参数。第一次执行的时候第一参数的值是流中第一元素，第二个元素是流中第二元素，因为流可能为空，所以这个方法的返回值为 Optional。

最容易想到的一个例子是通过 reduce 来求和：

Optional<Integer> result = students.map(Student::getAge).reduce((x, y) -> x + y);

其中的 Lambda 表达式 (x, y) -> x + y 也可以简写成方法引用 Integer::sum：

Optional<Integer> result = students.map(Student::getAge).reduce(Integer::sum);

不仅如此，稍微改一下 accumulator 函数，我们还可以实现其他的功能，比如求最大值：

Optional<Integer> result = students.map(Student::getAge).reduce((x, y) -> x > y ? x : y);

求最小值：

Optional<Integer> result = students.map(Student::getAge).reduce((x, y) -> x < y ? x : y);

这些参数同样也都可以使用方法引用 Integer::max 和 Integer::min 进行简化。

reduce 的第二种形式是：

T reduce(T identity, BinaryOperator<T> accumulator);

它和第一种形式的区别在于多了一个和流中元素同类型的 T identity 参数，这个参数的作用是设置初始值，当流中元素为空时，返回初始值。这个形式的好处是不会返回 Optional 类型，代码看起来更简单，所以一般更推荐使用这种形式：

Integer result = students.map(Student::getAge).reduce(0, Integer::sum);

在 reduce 的 JDK 源码注释里，有一段伪代码很好地解释了 reduce 内部的处理逻辑：

U result = identity;
for (T element : this stream)
    result = accumulator.apply(result, element)
return result;

reduce 的第三种形式如下：

<U> U reduce(U identity, 
    BiFunction<U, ? super T, U> accumulator, 
    BinaryOperator<U> combiner);

可以看到第三种形式要稍微复杂一点，它接受三个参数，第一个参数 identity 表示初始值，第二个参数 accumulator 表示累加器，这和形式二是一样的，不过注意看会发现这两个参数的类型发生了变化，而且返回值的类型也变了，不再局限于和流中元素同类型。第三个参数 BinaryOperator<U> combiner 被称为组合器，这个参数有什么作用呢？在上面的例子中，我们使用的都是串行流，当我们处理并行流时，流会被拆分成多个子流进行 reduce 操作，很显然我们还需要将多个子流的处理结果进行汇聚，这个汇聚操作就是 combiner。

不过如果你的汇聚操作和累加器逻辑是一样的，combiner 参数也可以省略：

Integer result = intStream.parallel().reduce(0, Integer::sum);

这个写法和下面的写法没有任何区别：

Integer result = intStream.parallel().reduce(0, Integer::sum, Integer::sum);

到目前为止我们还没有看到 reduce 方法的特别之处，可能你会觉得它不过就是普通的方法，用于 对流中的所有元素累积处理，最终得到一个处理结果。其实这是一个非常强大的工具，也是一个抽象程度非常高的概念，它的用法可以非常灵活，从下面几个例子可以一窥 reduce 的冰山一角。

统计元素个数：

Stream<Integer> intStream = Stream.of(1, 3, 2, 4, 2, 4, 2);
Map<Integer, Integer> countMap = intStream.reduce(new HashMap<>(), (x, y) -> {
    if (x.containsKey(y)) {
        x.put(y, x.get(y) + 1);
    } else {
        x.put(y, 1);
    }
    return x;
}, (x, y) -> new HashMap<>());

数组去重：

Stream<Integer> intStream = Stream.of(1, 3, 2, 4, 2, 4, 2);
List<Integer> distinctMap = intStream.reduce(new ArrayList<>(), (x, y) -> {
    if (!x.contains(y)) {
        x.add(y);
    }
    return x;
}, (x, y) -> new ArrayList<>());

List 转 Map：

Map<Long, Student> studentMap = students.reduce(new HashMap<Long, Student>(), (x, y) -> {
    x.put(y.getNumber(), y);
    return x;
}, (x, y) -> new HashMap<Long, Student>());

可以看到，一旦这个返回类型不做限制时，我们能做的事情就太多了。只要是类似的汇聚操作，都可以用 reduce 实现，这也是 MapReduce 可以用于大规模数据处理的原因。不过上面处理的都是串行流，所以 combiner 参数并没有什么用，随便写都不影响处理结果，但是当我们处理并行流时，combiner 参数就不能乱写了，也不能省略，这是因为它和累加器的参数是不一样的，而且它们的处理逻辑也略有区别。比如上面的 List 转 Map 的例子，如果使用并行流，则必须写 combiner 参数：

Map<Long, Student> studentMap = students.parallel().reduce(new HashMap<Long, Student>(), (x, y) -> {
    x.put(y.getNumber(), y);
    return x;
}, (x, y) -> {
    for (Map.Entry<Long, Student> entry : y.entrySet()) {
        x.put(entry.getKey(), entry.getValue());
    }
    return x;
});

collect

collect 函数正如它的名字一样，可以将流中的元素经过处理并收集起来，得到收集后的结果，这听起来感觉和 reduce 函数有点像，而且它的函数定义也和 reduce 函数很类似：

<R> R collect(Supplier<R> supplier,
    BiConsumer<R, ? super T> accumulator,
    BiConsumer<R, R> combiner);

不过区别还是有的，collect 函数的第一个参数也是用于设置初始值，不过它是通过一个 Supplier<R> supplier 来设置，这是一个没有参数的函数，函数的返回值就是初始值。第二个和第三个参数也是累加器 accumulator 和组合器 combiner，它们的作用和在 reduce 中是一样的，不过它们的类型是 BiConsumer 而不是 BinaryOperator（也不是 BiFunction），这也就意味着累加器和组合器是没有返回值的，所以需要在累加器中使用引用类型来储存中间结果，下面是使用 collect 对流中元素求和的例子：

Stream<Integer> intStream = Stream.of(1, 3, 2, 4);
AtomicInteger result = intStream.collect(
    () -> new AtomicInteger(),
    (a, b) -> a.addAndGet(b), 
    (a, b) -> {}
);

将上面的代码和 reduce 求和的代码对比一下，可以看出两者几乎是一样的，一般来说 reduce 能实现的功能，collect 基本上也都能实现，区别在于它的初始值是一个引用变量，并且中间的计算结果也一直储存在这个引用变量中，最后的返回值也是这个引用变量。很显然，这个引用变量是一个 可变的容器（mutable container），所以 collect 在官方文档中也被称为 Mutable reduction 操作。

而且 collect 相比于 reduce 来说显得更强大，因为它还提供了一个更简单的形式，它将 supplier、accumulator 和 combiner 抽象为收集器 Collector 接口：

<R, A> R collect(Collector<? super T, A, R> collector);

这个函数的定义虽然看上去非常简单，但是不得不说，collect 可能是 Stream API 中最为复杂的函数，其复杂之处就在于收集器的创建，为了方便我们创建收集器，Stream API 提供了一个工具类 Collectors，它内置了大量的静态方法可以创建一些常用的收集器，比如我们最常用的 Collectors.toList() 可以将流中元素收集为一个列表：

List<Integer> result = intStream.collect(Collectors.toList());

从源码中可以看出这个收集器是由 ArrayList::new 和 List::add 组成的：

public static <T>
Collector<T, ?, List<T>> toList() {
    return new CollectorImpl<>(
        (Supplier<List<T>>) ArrayList::new, 
        List::add,
        (left, right) -> { left.addAll(right); return left; },
        CH_ID);
}

上面 reduce 中的几个例子，我们一样可以使用 collect 来实现，比如求和：

Integer result = intStream.collect(Collectors.summingInt(Integer::valueOf));

求最大值：

Optional<Integer> result = intStream.collect(Collectors.maxBy(Integer::compareTo));

统计元素个数：

Map<Integer, Long> result = intStream.collect(Collectors.groupingBy(i -> i, Collectors.counting()));

数组去重：

Map<Integer, Integer> result = intStream.collect(Collectors.toMap(i -> i, i -> i, (i, j) -> i));

List 转 Map：

Map<Long, Student> result = students.collect(Collectors.toMap(Student::getNumber, Function.identity()));

除此之外，Collectors 还内置了很多其他的静态方法，比如字符串拼接：

String result = students.map(Student::getName).collect(Collectors.joining("、"));

按条件将数据分为两组：

Map<Boolean, List<Student>> result = students.collect(Collectors.partitioningBy(x -> x.getAge() > 30));

按字段值将数据分为多组：

Map<Integer, List<Student>> result = students.collect(Collectors.groupingBy(Student::getAge));

partitioningBy 和 groupingBy 函数非常类似，只不过一个将数据分成两组，一个将数据分为多组，它们的第一个参数都是 Function<? super T, ? extends K> classifier，又被称为 分类函数（classification function），分组返回的 Map 的键就是由它产生的，而对应的 Map 的值是该分类的数据列表。很容易想到，既然得到了每个分类的数据列表，我们当然可以继续使用 Stream API 对每个分类的数据进一步处理。所以 groupingBy 函数还提供了另一种形式：

Collector<T, ?, Map<K, D>> groupingBy(
    Function<? super T, ? extends K> classifier, 
    Collector<? super T, A, D> downstream)

第二个参数仍然是一个收集器 Collector，这被称为 下游收集器（downstream collector），比如上面那个统计元素个数的例子：

Map<Integer, Long> result = intStream.collect(Collectors.groupingBy(i -> i, Collectors.counting()));

这里就使用了下游收集器 Collectors.counting() 对每个分组的数据进行计数。我们甚至可以对下游收集器返回的结果继续使用下游收集器处理，比如我希望得修改分组后的数据类型：

Map<String, List<String>> result = students.collect(Collectors.groupingBy(
    Student::getGender, Collectors.mapping(
        Student::getName, Collectors.toList())));

这里我希望按学生性别分组，并得到每个性别的学生姓名列表，而不是学生列表。首先使用收集器 Collectors.mapping() 将 Student 对象转换为姓名，然后再使用 Collectors.toList() 将学生姓名收集到一个列表。这种包含一个或多个下游收集器的操作被称为 Multi-level reduction。

count

count 比较简单，用于统计流中元素个数：

long count = students.count();

max / min

max 和 min 函数用于计算流中的最大元素和最小元素，元素的大小通过比较器 Comparator<? super T> comparator 来决定。比如获取年龄最大的学生：

Optional<Student> maxAgeStudent = students.max(Comparator.comparingInt(Student::getAge));

不过对于基础类型流，max 和 min 函数进行了简化，不需要比较器参数：

OptionalInt maxAge = students.mapToInt(Student::getAge).max();

sum / average / summaryStatistics

另外，对于基础类型流，还特意增加了一些统计类的函数，比如 sum 用于对流中数据进行求和：

int sumAge = students.mapToInt(Student::getAge).sum();

average 用于求平均值：

OptionalDouble averageAge = students.mapToInt(Student::getAge).average();

summaryStatistics 用于一次性获取流中数据的统计信息（包括最大值、最小值、总和、数量、平均值）：

IntSummaryStatistics summaryStatistics = students.mapToInt(Student::getAge).summaryStatistics();
System.out.println("Max = " + summaryStatistics.getMax());
System.out.println("Min = " + summaryStatistics.getMin());
System.out.println("Sum = " + summaryStatistics.getSum());
System.out.println("Count = " + summaryStatistics.getCount());
System.out.println("Average = " + summaryStatistics.getAverage());

参考

1. Java8 Stream的总结
2. Java 8 新特性 | 菜鸟教程
3. Java 8 Stream | 菜鸟教程
4. Package java.util.stream Description
5. https://www.baeldung.com/java-streams
6. https://www.baeldung.com/tag/java-streams/
7. https://www.cnblogs.com/wangzhuxing/p/10204894.html
8. https://www.cnblogs.com/yulinfeng/p/12561664.html

更多

Collectors 静态方法一览

• 转换为集合

  • Collector<T, ?, C> toCollection(Supplier<C> collectionFactory)
  • Collector<T, ?, List<T>> toList()
  • Collector<T, ?, Set<T>> toSet()

• 统计计算

  • Collector<T, ?, IntSummaryStatistics> summarizingInt(ToIntFunction<? super T> mapper)
  • Collector<T, ?, LongSummaryStatistics> summarizingLong(ToLongFunction<? super T> mapper)
  • Collector<T, ?, DoubleSummaryStatistics> summarizingDouble(ToDoubleFunction<? super T> mapper)
  • Collector<T, ?, Optional<T>> minBy(Comparator<? super T> comparator)
  • Collector<T, ?, Optional<T>> maxBy(Comparator<? super T> comparator)
  • Collector<T, ?, Integer> summingInt(ToIntFunction<? super T> mapper)
  • Collector<T, ?, Long> summingLong(ToLongFunction<? super T> mapper)
  • Collector<T, ?, Double> summingDouble(ToDoubleFunction<? super T> mapper)
  • Collector<T, ?, Double> averagingInt(ToIntFunction<? super T> mapper)
  • Collector<T, ?, Double> averagingLong(ToLongFunction<? super T> mapper)
  • Collector<T, ?, Double> averagingDouble(ToDoubleFunction<? super T> mapper)
  • Collector<T, ?, Long> counting()

• 字符串拼接

  • Collector<CharSequence, ?, String> joining()
  • Collector<CharSequence, ?, String> joining(CharSequence delimiter)
  • Collector<CharSequence, ?, String> joining(CharSequence delimiter, CharSequence prefix, CharSequence suffix)

• Map & Reduce

  • Collector<T, ?, R> mapping(Function<? super T, ? extends U> mapper, Collector<? super U, A, R> downstream)
  • Collector<T, ?, T> reducing(T identity, BinaryOperator<T> op)
  • Collector<T, ?, Optional<T>> reducing(BinaryOperator<T> op)
  • Collector<T, ?, U> reducing(U identity, Function<? super T, ? extends U> mapper, BinaryOperator<U> op)

• 分组

  • Collector<T, ?, Map<K, List<T>>> groupingBy(Function<? super T, ? extends K> classifier)
  • Collector<T, ?, Map<K, D>> groupingBy(Function<? super T, ? extends K> classifier, Collector<? super T, A, D> downstream)
  • Collector<T, ?, M> groupingBy(Function<? super T, ? extends K> classifier, Supplier<M> mapFactory, Collector<? super T, A, D> downstream)
  • Collector<T, ?, ConcurrentMap<K, List<T>>> groupingByConcurrent(Function<? super T, ? extends K> classifier)
  • Collector<T, ?, ConcurrentMap<K, D>> groupingByConcurrent(Function<? super T, ? extends K> classifier, Collector<? super T, A, D> downstream)
  • Collector<T, ?, M> groupingByConcurrent(Function<? super T, ? extends K> classifier, Supplier<M> mapFactory, Collector<? super T, A, D> downstream)
  • Collector<T, ?, Map<Boolean, List<T>>> partitioningBy(Predicate<? super T> predicate)
  • Collector<T, ?, Map<Boolean, D>> partitioningBy(Predicate<? super T> predicate, Collector<? super T, A, D> downstream)

• List 转 Map

  • Collector<T, ?, Map<K,U>> toMap(Function<? super T, ? extends K> keyMapper, Function<? super T, ? extends U> valueMapper)
  • Collector<T, ?, Map<K,U>> toMap(Function<? super T, ? extends K> keyMapper, Function<? super T, ? extends U> valueMapper, BinaryOperator<U> mergeFunction)
  • Collector<T, ?, M> toMap(Function<? super T, ? extends K> keyMapper, Function<? super T, ? extends U> valueMapper, BinaryOperator<U> mergeFunction, Supplier<M> mapSupplier)
  • Collector<T, ?, ConcurrentMap<K,U>> toConcurrentMap(Function<? super T, ? extends K> keyMapper, Function<? super T, ? extends U> valueMapper)
  • Collector<T, ?, ConcurrentMap<K,U>> toConcurrentMap(Function<? super T, ? extends K> keyMapper, Function<? super T, ? extends U> valueMapper, BinaryOperator<U> mergeFunction)
  • Collector<T, ?, M> toConcurrentMap(Function<? super T, ? extends K> keyMapper, Function<? super T, ? extends U> valueMapper, BinaryOperator<U> mergeFunction, Supplier<M> mapSupplier)

• 其他

  • Collector<T,A,RR> collectingAndThen(Collector<T,A,R> downstream, Function<R,RR> finisher)

Visual Studio Code（简称 VS Code）是微软于 2015 年 4 月在微软开发者大会（Microsoft Build 2015）上开源的一款非常优秀的跨平台源代码编辑器，它不仅原生支持 JavaScript、TypeScript、CSS 和 HTML，而且可以通过强大的插件系统支持其他任意的编程语言，比如：Python、Java、C/C++、Go 等等。你可以在 插件市场 找到更多其他的插件。通过统一的接口模型，VS Code 为不同的编程语言提供了统一的编程体验，你再也不需要在不同语言的 IDE 之间来回切换了。

VS Code 为不同的编程语言提供了如下通用的语言特性：

• 语法高亮（Syntax highlighting）、括号匹配（Bracket matching）
• 代码自动补全（IntelliSense）
• 语法检查（Linting and corrections）
• 代码导航（Go to Definition, Find All References）
• 调试
• 重构

VS Code 使用 Monaco Editor 作为其底层的代码编辑器，不仅可以跨平台使用，而且还可以通过浏览器在线使用，你可以访问 vscode.dev，操作界面和桌面版几乎是一样的。在 2019 年的 Stack Overflow 组织的开发者调查中，VS Code 被认为是最受开发者欢迎的开发环境。

安装 Go 插件

Go 语言 又被称为 Golang，是 Google 开发的一种静态强类型、编译型、并发型，并具有垃圾回收功能的编程语言。它于 2007 年 9 月开始设计，并在 2009 年 11 月正式发布并完全开源，至今已有 13 年的历史了。目前的 Go 语言在国内外的技术社区都非常热门，并诞生了很多著名的开源项目，如 Kubernetes、etcd 和 Prometheus 等，在近年来热门的微服务架构和云原生技术的发展中起到了举足轻重的作用。

在这篇笔记中，我们将学习如何在 VS Code 中进行 Go 语言的开发。

首先打开官网的 Download and install 页面，按照提示的步骤下载并安装 Go 语言开发环境。

然后在 VS Code 中安装 Go 插件：

此时，我们只需要打开以 .go 结尾的文件，就可以激活该插件，左下角会显示出 Go 的状态栏，并在状态栏上可以看到当前使用的 Go 版本：

另外，这个插件还依赖 一些 Go 工具，比如 gopls、dlv 等。gopls 是 Go 官方的 language server，dlv 使用 Delve 进行 Go 语言的调试和测试，都是开发过程中必不可少的组件。如果其中任何一个工具缺失，VS Code 下面的状态栏就会弹出 ⚠️ Analysis Tools Missing 的警告提示，点击提示将自动下载安装这些工具：

安装完成后，一切准备就绪，就可以开始我们的 Go 语言之旅了。

You are ready to Go :-)

从这里可以看到 Go 插件支持的 所有特性。

Go 入门示例

这一节我们将演示如何在 VS Code 中开发一个 Go 项目。首先创建一个空目录 demo，并在 VS Code 中打开它。然后我们新建一个终端，输入下面的命令创建一个 Go 模块（module）：

$ go mod init example.com/demo
go: creating new go.mod: module example.com/demo

运行成功后，可以发现创建了一个 go.mod 文件，这个文件类似于 Maven 项目中 pom.xml 文件，用于管理项目依赖的模块。早期的版本中，Go 语言是没有依赖管理功能的，所有依赖的第三方包都放在 GOPATH 目录下，这就导致了同一个包只能保存一个版本，如果不同的项目依赖同一个包的不同版本，该怎么办呢？

于是 Go 语言从 v1.5 版本开始引入 vendor 模式，如果项目目录下有 vendor 目录，那么 Go 会优先使用 vendor 内的包，可以使用 godep 或 dep 来管理 vender 模式下的依赖包。

不过从 v1.11 版本开始，官方又推出了 Go module 功能，并在 v1.13 版本中作为 Go 语言默认的依赖管理工具。使用 Go module 依赖管理会在项目根目录下生成 go.mod 和 go.sum 两个文件。

我们打开 go.mod 这个文件，目前内容还比较简单，只是定义了当前的模块名以及使用的 Go 版本：

module example.com/demo

go 1.19

接下来我们在项目中创建一个 包（package），也就是一个目录，比如 hello，并在该目录下创建一个文件 hello.go，打开这个文件时会激活 Go 插件。等插件加载完毕，我们就可以编写 Go 代码了，在文件中输入如下内容：

package hello

func SayHello() string {
    return "Hello world"
}

第一行使用 package 声明包，然后下面通过 func 定义了一个 SayHello() string 方法，注意在 Go 语言中类型是写在方法名后面的。

接下来，在项目根目录下创建一个 main.go 文件，内容如下：

package main

import (
    "fmt"

    "example.com/demo/hello"
)

func main() {
    fmt.Println(hello.SayHello())
}

第一行依然是使用 package 来声明包，每个 .go 文件都需要声明包，只不过包名不同；然后使用 import 导入我们要使用的包，这里我们使用了 fmt 这个系统包，它是用于打印输出的，还使用了我们上面创建的 example.com/demo/hello 这个包，这样我们就可以调用其他包里的方法了；最后通过 func 定义了一个 main() 方法，这个方法是整个程序的入口。

就这样一个简单的示例项目就完成了。我们打开终端，输入 go run 命令即可运行程序：

$ go run main.go
Hello world

或者使用 go build 将代码编译为可执行程序：

$ go build main.go

运行生成的可执行程序：

$ ./main
Hello world

引用三方包

上面的例子中我们只使用了系统包和自己代码中的包，如果要使用第三方包该怎么办呢？

我们可以使用 go get 下载第三方包并将依赖更新到 go.mod 文件中，比如我们要添加 rsc.io/quote 这个依赖包，执行如下命令：

$ go get rsc.io/quote
go: downloading rsc.io/quote v1.5.2
go: added golang.org/x/text v0.0.0-20170915032832-14c0d48ead0c
go: added rsc.io/quote v1.5.2

这个命令默认会从 Go 官方的模块代理（https://proxy.golang.org）下载依赖包，如果遇到网络问题，可以使用下面的命令改为国内的代理（https://goproxy.cn）：

$ go env -w GOPROXY=https://goproxy.cn,direct

go get 命令执行成功后，重新打开 go.mod 文件，可以看到自动添加了依赖：

require (
    golang.org/x/text v0.0.0-20170915032832-14c0d48ead0c // indirect
    rsc.io/quote v1.5.2 // indirect
    rsc.io/sampler v1.3.0 // indirect
)

这时我们就可以在代码中使用 rsc.io/quote 这个包了：

package main

import (
    "fmt"

    "example.com/demo/hello"
    "rsc.io/quote"
)

func main() {
    fmt.Println(hello.SayHello())
    fmt.Println(quote.Go())
}

重新运行程序：

$ go run main.go
Hello world
Don't communicate by sharing memory, share memory by communicating.

编写单元测试

这一节我们使用 Go 语言的标准库 testing 对我们的代码进行单元测试。Go 语言推荐将测试文件和源代码文件放在一起，测试文件以 _test.go 结尾，比如我们要对上面的 hello.go 编写单元测试，可以在同目录创建一个 hello_test.go 文件，文件内容如下：

package hello_test

import (
    "testing"

    "example.com/demo/hello"
)

func TestSayHello(t *testing.T) {
    if hello.SayHello() != "Hello world" {
        t.Fatal("Not good")
    }
}

测试用例名称一般命名为 Test 加上待测试的方法名，比如这里的 TestSayHello 是对 SayHello 的测试，测试用的参数有且只有一个，在这里是 t *testing.T，表示这是一个单元测试，如果是基准测试，这个参数类型为 *testing.B。

VS Code 会自动识别单元测试的包和方法，并在包和方法上显示一个链接：

我们可以点击方法上的 run test 或 debug test 来执行测试，或者使用 go test 命令来执行，由于这个测试是写在 hello 这个目录下，我们需要进入该目录执行测试：

$ cd hello
$ go test
PASS
ok      example.com/demo/hello  0.277s

这里有一点需要特别注意，我们在这个文件的最顶部声明包时用的是 package hello_test，而不是 package hello，其实两种方法都可以，这取决于你编写的是黑盒测试还是白盒测试。如果你使用 package hello，那么在单元测试代码中就可以对私有方法进行测试，相当于白盒测试，而这里我们使用的是黑盒测试，也就是只对包里公共方法进行测试。

调试 Go 程序

在上面的单元测试方法上面有一个 debug test 链接，点击该链接就可以调试 Go 程序了。如果要以调试模式启动 main() 函数，可以打开 main.go 文件，使用 F5 快捷键启动调试器。

或者打开 VS Code 的 “运行和调试” 侧边栏，然后点击 “运行和调试” 按钮也可以启动调试器。如果调试器启动成功，我们可以在下方的调试控制台看到类似这样的输出：

Starting: C:\Users\aneasystone\go\bin\dlv.exe dap --check-go-version=false --listen=127.0.0.1:60508 from d:\code\weekly-practice\notes\week021-go-in-visual-studio-code\demo
DAP server listening at: 127.0.0.1:60508

Go 语言的官方调试器是 dlv，它的全称为 Delve，VSCode 通过运行 dlv dap 命令来启动 Go 语言的调试器，这个命令会在本地启动一个 TCP 服务器，并通过 DAP 协议（Debug Adaptor Protocol）) 和 VS Code 进行通信实现调试的功能。

使用 F5 快捷键或 “运行和调试” 按钮时，VS Code 会使用默认配置对当前打开的文件进行调试。如果想修改配置参数，我们可以创建一个 launch.json 配置文件：

点击 “创建 launch.json 文件” 按钮会弹出一个下拉框，我们可以：

• 调试一个包（Launch Package）
• 附加到本地进程（Attach to local process）
• 连接到远程服务（Connect to server）

我们选择第一个，创建的 launch.json 配置文件如下：

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Launch Package",
            "type": "go",
            "request": "launch",
            "mode": "auto",
            "program": "${fileDirname}"
        }
    ]
}

我们将 ${fileDirname} 变量修改为 .，表示项目的根目录。这样我们就可以在打开任意文件的时候快速调试 main() 方法了，而不用每次都打开 main.go 文件来调试。如果我们需要对调试器进行配置，比如配置命令行参数启动（args），修改当前工作目录（cwd），配置 dlv 调试器（dlvFlags）等等，我们在 launch.json 中输入引号后 VS Code 会自动提示所有支持的配置项：

这些配置项的含义可以参考 Launch.json Attributes。

参考

1. Go in Visual Studio Code
2. VSCode Go Wiki
3. Go Documentation
4. Getting started with VS Code Go
5. Go语言之依赖管理
6. Go Test 单元测试简明教程
7. Proper package naming for testing with the Go language
8. Debug Go programs in VS Code

Kubernetes Operator 这一概念是由 CoreOS 的工程师于 2016 年提出的，它是一种通过 自定义资源（custom resource、CR）来包装、运行和管理 Kubernetes 应用的方式。Kubernetes 1.7 版本以来就引入了自定义资源的概念，该功能可以让开发人员扩展新功能或更新现有功能，并且可以自动执行一些管理任务，这些自定义资源就像 Kubernetes 的原生组件一样。

通过自定义资源，我们可以将应用抽象为一个整体，而不用去关心该应用是由哪些 Kubernetes 原生组件构成的，什么 Pods、Deployments、Services 或 ConfigMaps 统统交给 Operator 来管理。创建 Operator 的关键是自定义资源的设计，通过直接调用 Kubernetes API，编写自定义规则自动管理和维护 Kubernetes 集群中的应用，包括自动化安装、配置、更新、故障转移、备份恢复等等。这样的应用也被称为 Kubernetes 原生应用（Kubernetes-native application）。可以把 Operator 当做是一个运维人员，它以软件的形式帮助我们管理 Kubernetes 中运行的应用。Operator 可以帮我们实现下面这些运维工作：

这个图也被称为 Operator 的能力模型，将 Operator 的能力由低到高分成了 5 个等级。

控制器循环

Kubernetes Operator 遵循 control loop 原则，这是 Kubernetes 的核心原则之一，也是机器人和自动化领域中一种常见的持续运行动态系统的机制。它依赖于一种快速调整工作负载需求的能力，进而能够尽可能准确地适应现有资源。

在 Kubernetes 中，这个循环被称为 reconciliation loop。在这个循环中，有一个非常重要的角色：控制器（Controller），它可以对集群的变化做出响应，并执行相应的动作。控制器首先观察 Kubernetes 对象的当前状态，然后通过 Kubernetes API 进行持续调整，直到将对象的当前状态变成所需状态为止。

第一个 Kubernetes Controller 是 kube-controller-manager，它被认为是所有 Operator 的鼻祖。

使用 Operator Framework 开发 Operator

Operator Framework 是 CoreOS 开源的一个用于快速开发或管理 Operator 的工具包，主要分为三大部分：

• Operator SDK：Build, test, iterate. 你无需了解复杂的 Kubernetes API 特性，就可以根据你自己的专业知识构建一个 Operator 应用。
• Operator Lifecycle Manager：install, manage, update. OLM 是一款帮助你安装、更新和管理 Kubernetes Operator 的工具。
• OperatorHub.io：Publish & share. OperatorHub 是一个类似 DockerHub 的仓库，你可以在这里搜索你想要的 Operator，或者将你的 Operator 发布并分享给其他人。

通过 Operator SDK 我们可以快速开发一个 Kubernetes Operator，它不仅提供了一套 High level API 来方便我们处理业务逻辑，还提供了一个命令行工具用于快速生成一个 Operator 的脚手架项目。

安装 operator-sdk

在开发 Operator 之前，先确保你已经有一个能访问的 Kubernetes 集群环境，Kubernetes 的安装可以参考 Kubernetes 安装小记。查看 Kubernetes 集群信息：

$ kubectl cluster-info
Kubernetes control plane is running at https://kubernetes.docker.internal:6443
CoreDNS is running at https://kubernetes.docker.internal:6443/api/v1/namespaces/kube-system/services/kube-dns:dns/proxy

To further debug and diagnose cluster problems, use 'kubectl cluster-info dump'.

另外，Go 的开发环境也是必不可少的，可以参考 Go 的 官方文档 下载并安装。

$ curl -LO https://go.dev/dl/go1.19.linux-amd64.tar.gz
$ sudo tar -C /usr/local -xzf go1.19.linux-amd64.tar.gz

将路径 /usr/local/go/bin 添加到 PATH 环境变量，或者将下面这行添加到 ~/.profile 文件中：

$ export PATH=$PATH:/usr/local/go/bin

查看 Go 版本：

$ go version
go version go1.19 linux/amd64

接下来，我们继续安装 Operator SDK。我们在 Operator SDK 的 Releases 页面 找到合适的版本并下载：

$ curl -LO https://github.com/operator-framework/operator-sdk/releases/download/v1.23.0/operator-sdk_linux_amd64

将其移动到 /usr/local/bin/ 目录即可完成安装：

$ chmod +x operator-sdk_linux_amd64 && sudo mv operator-sdk_linux_amd64 /usr/local/bin/operator-sdk

查看已安装的 operator-sdk 版本：

$ operator-sdk version
operator-sdk version: "v1.23.0", commit: "1eaeb5adb56be05fe8cc6dd70517e441696846a4", kubernetes version: "1.24.2", go version: "go1.18.5", GOOS: "linux", GOARCH: "amd64"

另外，operator-sdk 依赖于 make 和 gcc，确保系统上已经安装了 make 和 gcc 工具。

使用 operator-sdk 初始化 Operator 项目

Operator SDK 提供了三种方式开发 Operator：

• Ansible
• Helm
• Go

我们这里将使用 Go 来开发 Operator，这种方式也是最灵活的，你可以使用 client-go 调用 Kubernetes API 来对 Kubernetes 对象进行操作。首先使用 operator-sdk init 初始化项目结构：

$ operator-sdk init --domain example.com --project-name memcached-operator --repo github.com/example/memcached-operator
Writing kustomize manifests for you to edit...
Writing scaffold for you to edit...
Get controller runtime:
$ go get sigs.k8s.io/controller-runtime@v0.12.2
Update dependencies:
$ go mod tidy
Next: define a resource with:
$ operator-sdk create api

其中 --project-name 参数可以省略，默认项目名称就是目录名。--domain 和 --project-name 两个参数用于组成 Operator 的镜像名称 example.com/memcached-operator，而 --repo 参数用于定义 Go 模块名：

module github.com/example/memcached-operator

初始化后的完整项目结构如下：

$ tree .
.
├── Dockerfile
├── Makefile
├── PROJECT
├── README.md
├── config
│   ├── default
│   │   ├── kustomization.yaml
│   │   ├── manager_auth_proxy_patch.yaml
│   │   └── manager_config_patch.yaml
│   ├── manager
│   │   ├── controller_manager_config.yaml
│   │   ├── kustomization.yaml
│   │   └── manager.yaml
│   ├── manifests
│   │   └── kustomization.yaml
│   ├── prometheus
│   │   ├── kustomization.yaml
│   │   └── monitor.yaml
│   ├── rbac
│   │   ├── auth_proxy_client_clusterrole.yaml
│   │   ├── auth_proxy_role.yaml
│   │   ├── auth_proxy_role_binding.yaml
│   │   ├── auth_proxy_service.yaml
│   │   ├── kustomization.yaml
│   │   ├── leader_election_role.yaml
│   │   ├── leader_election_role_binding.yaml
│   │   ├── role_binding.yaml
│   │   └── service_account.yaml
│   └── scorecard
│       ├── bases
│       │   └── config.yaml
│       ├── kustomization.yaml
│       └── patches
│           ├── basic.config.yaml
│           └── olm.config.yaml
├── go.mod
├── go.sum
├── hack
│   └── boilerplate.go.txt
└── main.go

主要包括以下几个文件：

• go.mod - 用于定义 Go 项目的依赖信息
• PROJECT - 用于保存项目的配置信息
• Makefile - 包含一些有用的项目构建目标（make targets）
• config - 该目录下包含一些用于项目部署的 YAML 文件
• main.go - Operator 的主程序入口

创建 API

初始化项目之后，接着就可以使用 operator-sdk create api 命令创建 API 了：

$ operator-sdk create api --group cache --version v1alpha1 --kind Memcached --resource --controller
Writing kustomize manifests for you to edit...
Writing scaffold for you to edit...
api/v1alpha1/memcached_types.go
controllers/memcached_controller.go
Update dependencies:
$ go mod tidy
Running make:
$ make generate
./memcached-operator/bin/controller-gen object:headerFile="hack/boilerplate.go.txt" paths="./..."
Next: implement your new API and generate the manifests (e.g. CRDs,CRs) with:
$ make manifests

使用 operator-sdk create 命令可以生成 api 或 webhook 的脚手架代码，我们这里生成的是 api，包括两部分内容：自定义资源（--resource）和控制器相关的逻辑代码（--controller），其中 --group、--version 和 --kind 分别用来设置资源的分组、版本和类型。

接下来可以从这些文件开始入手：

• api/v1beta1/memcached_types.go
• controllers/memcached_controller.go
• controllers/suite_test.go

memcached_types.go 文件用于定义资源的接口规范，我们在 MemcachedSpec 中添加一个新字段 Size 如下（默认已经生成了一个 Foo 字段）：

// MemcachedSpec defines the desired state of Memcached
type MemcachedSpec struct {
    // INSERT ADDITIONAL SPEC FIELDS - desired state of cluster
    // Important: Run "make" to regenerate code after modifying this file

    // Foo is an example field of Memcached. Edit memcached_types.go to remove/update
    Foo string `json:"foo,omitempty"`
    Size int32 `json:"size"`
}

接着打开 memcached_controller.go 文件，其中 Reconcile 方法就是上面所介绍的 reconciliation loop 的核心代码，可以在这里实现自己的业务逻辑，比如调用 Kubernetes API 创建、删除或更新各种 Kubernetes 资源。我们这里只是简单地将资源的属性值打印出来（官方对 memcached-operator 有完整的示例代码，可以 参考这里）：

func (r *MemcachedReconciler) Reconcile(ctx context.Context, req ctrl.Request) (ctrl.Result, error) {
    _ = log.FromContext(ctx)

    instance := &cachev1alpha1.Memcached{}
    err := r.Get(context.TODO(), req.NamespacedName, instance)
    if err != nil {
        fmt.Println("Get instance err")
        return ctrl.Result{}, err
    }

    fmt.Printf("Foo = %s, Size = %d\n", instance.Spec.Foo, instance.Spec.Size)

    return ctrl.Result{}, nil
}

然后执行下面的命令生成自定义资源文件：

$ make manifests
test -s ./memcached-operator/bin/controller-gen || GOBIN=./memcached-operator/bin go install sigs.k8s.io/controller-tools/cmd/controller-gen@v0.9.2
./memcached-operator/bin/controller-gen rbac:roleName=manager-role crd webhook paths="./..." output:crd:artifacts:config=config/crd/bases

生成的自定义资源文件位于 config/crd/bases/cache.example.com_memcacheds.yaml，文件内容如下：

---
apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
  annotations:
    controller-gen.kubebuilder.io/version: v0.9.2
  creationTimestamp: null
  name: memcacheds.cache.example.com
spec:
  group: cache.example.com
  names:
    kind: Memcached
    listKind: MemcachedList
    plural: memcacheds
    singular: memcached
  scope: Namespaced
  versions:
  - name: v1alpha1
    schema:
      openAPIV3Schema:
        description: Memcached is the Schema for the memcacheds API
        properties:
          apiVersion:
            description: 'APIVersion defines the versioned schema of this representation
              of an object. Servers should convert recognized schemas to the latest
              internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources'
            type: string
          kind:
            description: 'Kind is a string value representing the REST resource this
              object represents. Servers may infer this from the endpoint the client
              submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds'
            type: string
          metadata:
            type: object
          spec:
            description: MemcachedSpec defines the desired state of Memcached
            properties:
              foo:
                description: Foo is an example field of Memcached. Edit memcached_types.go
                  to remove/update
                type: string
              size:
                format: int32
                type: integer
            required:
            - size
            type: object
          status:
            description: MemcachedStatus defines the observed state of Memcached
            type: object
        type: object
    served: true
    storage: true
    subresources:
      status: {}

在这个文件中，我们定义了一个名为 Memcached 的自定义资源（Custom Resource Definition，简称 CRD），并定义了 foo 和 size 两个属性，且 size 属性为必填项。

本地调试 Operator

至此，一个简单的 Operator 就开发好了，接下来我们运行 make install 命令，该命令使用 kustomize build 生成 CRD 配置文件并执行 kubectl apply 将 CRD 安装到 Kubernetes 集群中：

$ make install
test -s ./memcached-operator/bin/controller-gen || GOBIN=./memcached-operator/bin go install sigs.k8s.io/controller-tools/cmd/controller-gen@v0.9.2
./memcached-operator/bin/controller-gen rbac:roleName=manager-role crd webhook paths="./..." output:crd:artifacts:config=config/crd/bases
./memcached-operator/bin/kustomize build config/crd | kubectl apply -f -
customresourcedefinition.apiextensions.k8s.io/memcacheds.cache.example.com created

通过 kubectl get crds 可以查看集群中的自定义资源是否创建成功：

$ kubectl get crds
NAME                           CREATED AT
memcacheds.cache.example.com   2022-08-26T09:24:19Z

可以看到集群中多了一个自定义资源 memcacheds.cache.example.com。然后运行 make run 命令在本地启动控制器：

$ make run
test -s ./memcached-operator/bin/controller-gen || GOBIN=./memcached-operator/bin go install sigs.k8s.io/controller-tools/cmd/controller-gen@v0.9.2
./memcached-operator/bin/controller-gen rbac:roleName=manager-role crd webhook paths="./..." output:crd:artifacts:config=config/crd/bases
./memcached-operator/bin/controller-gen object:headerFile="hack/boilerplate.go.txt" paths="./..."
go fmt ./...
api/v1alpha1/groupversion_info.go
go vet ./...
go run ./main.go
1.6615063195978441e+09  INFO    controller-runtime.metrics      Metrics server is starting to listen    {"addr": ":8080"}
1.6615063195986106e+09  INFO    setup   starting manager
1.6615063195992978e+09  INFO    Starting server {"path": "/metrics", "kind": "metrics", "addr": "[::]:8080"}
1.6615063195993063e+09  INFO    Starting server {"kind": "health probe", "addr": "[::]:8081"}
1.661506319599374e+09   INFO    Starting EventSource    {"controller": "memcached", "controllerGroup": "cache.example.com", "controllerKind": "Memcached", "source": "kind source: *v1alpha1.Memcached"}
1.6615063196000834e+09  INFO    Starting Controller     {"controller": "memcached", "controllerGroup": "cache.example.com", "controllerKind": "Memcached"}
1.6615063197010505e+09  INFO    Starting workers        {"controller": "memcached", "controllerGroup": "cache.example.com", "controllerKind": "Memcached", "worker count": 1}

接下来我们就可以创建一个自定义资源实例测试一下。首先修改 config/samples/cache_v1alpha1_memcached.yaml 文件，填入 foo 和 size 两个属性：

apiVersion: cache.example.com/v1alpha1
kind: Memcached
metadata:
  name: memcached-sample
spec:
  foo: Hello World
  size: 10

然后执行 kubectl apply 命令创建自定义资源实例：

$ kubectl apply -f config/samples/cache_v1alpha1_memcached.yaml
memcached.cache.example.com/memcached-sample created

此时查看控制器的输出如下：

Foo = Hello World, Size = 10

说明控制器监听到了自定义资源的创建，并输出了它的属性值。使用 kubectl get 查看刚刚创建的自定义资源：

$ kubectl get memcached.cache.example.com/memcached-sample
NAME               AGE
memcached-sample   13m

然后我们测试下自定义资源更新时的情况，修改 cache_v1alpha1_memcached.yaml 文件，比如将 size 改为 9，重新执行 kubectl apply 命令，控制器会立即监听到该修改，并输出新的属性值：

Foo = Hello World, Size = 9

部署 Operator

Operator 开发完成后，我们需要将它部署到 Kubernetes 集群中。首先我们将其构建成 Docker 镜像，可以使用下面的命令构建，并将镜像推送到镜像仓库：

$ make docker-build docker-push IMG="aneasystone/memcached-operator:v0.0.1"
test -s ./memcached-operator/bin/controller-gen || GOBIN=./memcached-operator/bin go install sigs.k8s.io/controller-tools/cmd/controller-gen@v0.9.2
./memcached-operator/bin/controller-gen rbac:roleName=manager-role crd webhook paths="./..." output:crd:artifacts:config=config/crd/bases
./memcached-operator/bin/controller-gen object:headerFile="hack/boilerplate.go.txt" paths="./..."
go fmt ./...
go vet ./...
KUBEBUILDER_ASSETS="/home/aneasystone/.local/share/kubebuilder-envtest/k8s/1.24.2-linux-amd64" go test ./... -coverprofile cover.out
?       github.com/example/memcached-operator   [no test files]
?       github.com/example/memcached-operator/api/v1alpha1      [no test files]
ok      github.com/example/memcached-operator/controllers       8.935s  coverage: 0.0% of statements
docker build -t aneasystone/memcached-operator:v0.0.1 .
[+] Building 3.3s (18/18) FINISHED                                                                                                                                
 => [internal] load build definition from Dockerfile
 => => transferring dockerfile: 38B                                                         0.0s
 => [internal] load .dockerignore                                                           0.0s
 => => transferring context: 35B                                                            0.0s
 => [internal] load metadata for gcr.io/distroless/static:nonroot                           0.7s
 => [internal] load metadata for docker.io/library/golang:1.18                              3.0s
 => [auth] library/golang:pull token for registry-1.docker.io0.0s
 => [builder 1/9] FROM docker.io/library/golang:1.18@sha256:5540a6a6b3b612c382accc545b3f6702de21e77b15d89ad947116c94b5f42993        0.0s
 => [internal] load build context                                                           0.1s
 => => transferring context: 3.84kB                                                         0.0s
 => [stage-1 1/3] FROM gcr.io/distroless/static:nonroot@sha256:1f580b0a1922c3e54ae15b0758b5747b260bd99d39d40c2edb3e7f6e2452298b     0.0s
 => CACHED [builder 2/9] WORKDIR /workspace                                                 0.0s
 => CACHED [builder 3/9] COPY go.mod go.mod                                                 0.0s
 => CACHED [builder 4/9] COPY go.sum go.sum                                                 0.0s
 => CACHED [builder 5/9] RUN go mod download                                                0.0s
 => CACHED [builder 6/9] COPY main.go main.go                                               0.0s
 => CACHED [builder 7/9] COPY api/ api/                                                     0.0s
 => CACHED [builder 8/9] COPY controllers/ controllers/                                     0.0s
 => CACHED [builder 9/9] RUN CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -a -o manager main.go                                   0.0s
 => CACHED [stage-1 2/3] COPY --from=builder /workspace/manager .                           0.0s
 => exporting to image                                                                      0.0s
 => => exporting layers                                                                     0.0s
 => => writing image sha256:84df51146080fec45fb74d5be29705f41c27de062e1192cb7c43a3a80c22977e                                        0.0s
 => => naming to docker.io/aneasystone/memcached-operator:v0.0.1                            0.0s
docker push aneasystone/memcached-operator:v0.0.1
The push refers to repository [docker.io/aneasystone/memcached-operator]
b399109810db: Pushed 
c456571abc85: Pushed 
v0.0.1: digest: sha256:60822319ac3578e3f62a73530c5ca08472014bf7861b75de6dd88502ee11d088 size: 739

上面我将镜像推送到 Docker 官方镜像仓库 docker.io，你也可以配置成自己的镜像仓库地址。

然后就可以将镜像部署到 Kubernetes 集群中了，官方提供了两种部署方式：直接部署 或 使用 OLM 部署。

直接部署

运行下面的 make deploy 命令：

$ make deploy IMG="aneasystone/memcached-operator:v0.0.1"
test -s ./memcached-operator/bin/controller-gen || GOBIN=./memcached-operator/bin go install sigs.k8s.io/controller-tools/cmd/controller-gen@v0.9.2
./memcached-operator/bin/controller-gen rbac:roleName=manager-role crd webhook paths="./..." output:crd:artifacts:config=config/crd/bases
test -s ./memcached-operator/bin/kustomize || { curl -s "https://raw.githubusercontent.com/kubernetes-sigs/kustomize/master/hack/install_kustomize.sh" | bash -s -- 3.8.7 ./memcached-operator/bin; }
cd config/manager && ./memcached-operator/bin/kustomize edit set image controller=aneasystone/memcached-operator:v0.0.1
./memcached-operator/bin/kustomize build config/default | kubectl apply -f -
namespace/memcached-operator-system created
customresourcedefinition.apiextensions.k8s.io/memcacheds.cache.example.com unchanged
serviceaccount/memcached-operator-controller-manager created
role.rbac.authorization.k8s.io/memcached-operator-leader-election-role created
clusterrole.rbac.authorization.k8s.io/memcached-operator-manager-role created
clusterrole.rbac.authorization.k8s.io/memcached-operator-metrics-reader created
clusterrole.rbac.authorization.k8s.io/memcached-operator-proxy-role created
rolebinding.rbac.authorization.k8s.io/memcached-operator-leader-election-rolebinding created
clusterrolebinding.rbac.authorization.k8s.io/memcached-operator-manager-rolebinding created
clusterrolebinding.rbac.authorization.k8s.io/memcached-operator-proxy-rolebinding created
configmap/memcached-operator-manager-config created
service/memcached-operator-controller-manager-metrics-service created
deployment.apps/memcached-operator-controller-manager created

从日志可以看到部署了一堆的东西，包括一个名字空间：

• namespace/memcached-operator-system created

一个自定义资源：

• customresourcedefinition.apiextensions.k8s.io/memcacheds.cache.example.com unchanged

一个 ConfigMap、Service 和 Deployment（这就是我们的 Operator）：

• configmap/memcached-operator-manager-config created
• service/memcached-operator-controller-manager-metrics-service created
• deployment.apps/memcached-operator-controller-manager created

还有一堆账户角色这些和安全相关的资源：

• serviceaccount/memcached-operator-controller-manager created
• role.rbac.authorization.k8s.io/memcached-operator-leader-election-role created
• clusterrole.rbac.authorization.k8s.io/memcached-operator-manager-role created
• clusterrole.rbac.authorization.k8s.io/memcached-operator-metrics-reader created
• clusterrole.rbac.authorization.k8s.io/memcached-operator-proxy-role created
• rolebinding.rbac.authorization.k8s.io/memcached-operator-leader-election-rolebinding created
• clusterrolebinding.rbac.authorization.k8s.io/memcached-operator-manager-rolebinding created
• clusterrolebinding.rbac.authorization.k8s.io/memcached-operator-proxy-rolebinding created

这些和正常的 Kubernetes 资源是完全一样的，我们可以使用 kubectl get 查询各个资源的详情，注意指定名字空间（-n memcached-operator-system）：

$ kubectl get deployment -n memcached-operator-system
NAME                                    READY   UP-TO-DATE   AVAILABLE   AGE
memcached-operator-controller-manager   1/1     1            1           9m6s

$ kubectl get pods -n memcached-operator-system
NAME                                                     READY   STATUS    RESTARTS   AGE
memcached-operator-controller-manager-689d94c9bf-bqv2q   2/2     Running   0          8m54s

$ kubectl get service -n memcached-operator-system
NAME                                                    TYPE        CLUSTER-IP     EXTERNAL-IP   PORT(S)    AGE
memcached-operator-controller-manager-metrics-service   ClusterIP   10.96.197.28   <none>        8443/TCP   11m

同样的，也可以使用 kubectl logs 查看 Operator 的日志：

$ kubectl logs -f memcached-operator-controller-manager-689d94c9bf-bqv2q -n memcached-operator-system

如果要卸载 Operator，执行 make undeploy 命令即可：

$ make undeploy
./memcached-operator/bin/kustomize build config/default | kubectl delete --ignore-not-found=false -f -
namespace "memcached-operator-system" deleted
customresourcedefinition.apiextensions.k8s.io "memcacheds.cache.example.com" deleted
serviceaccount "memcached-operator-controller-manager" deleted
role.rbac.authorization.k8s.io "memcached-operator-leader-election-role" deleted
clusterrole.rbac.authorization.k8s.io "memcached-operator-manager-role" deleted
clusterrole.rbac.authorization.k8s.io "memcached-operator-metrics-reader" deleted
clusterrole.rbac.authorization.k8s.io "memcached-operator-proxy-role" deleted
rolebinding.rbac.authorization.k8s.io "memcached-operator-leader-election-rolebinding" deleted
clusterrolebinding.rbac.authorization.k8s.io "memcached-operator-manager-rolebinding" deleted
clusterrolebinding.rbac.authorization.k8s.io "memcached-operator-proxy-rolebinding" deleted
configmap "memcached-operator-manager-config" deleted
service "memcached-operator-controller-manager-metrics-service" deleted
deployment.apps "memcached-operator-controller-manager" deleted

使用 OLM 部署

OLM 的全称为 Operator Lifecycle Manager，是一款用于 Operator 的管理工具，可以使用 OLM 来帮你安装或更新 Kubernetes Operator。我们首先通过 operator-sdk 安装 OLM：

$ operator-sdk olm install
INFO[0001] Fetching CRDs for version "latest"
INFO[0001] Fetching resources for resolved version "latest"
I0827 15:01:42.199954   12688 request.go:601] Waited for 1.0471208s due to client-side throttling, not priority and fairness, request: GET:https://kubernetes.docker.internal:6443/apis/autoscaling/v1?timeout=32s
INFO[0012] Creating CRDs and resources
INFO[0012]   Creating CustomResourceDefinition "catalogsources.operators.coreos.com"
INFO[0012]   Creating CustomResourceDefinition "clusterserviceversions.operators.coreos.com"
INFO[0012]   Creating CustomResourceDefinition "installplans.operators.coreos.com"
INFO[0012]   Creating CustomResourceDefinition "olmconfigs.operators.coreos.com"
INFO[0012]   Creating CustomResourceDefinition "operatorconditions.operators.coreos.com"
INFO[0012]   Creating CustomResourceDefinition "operatorgroups.operators.coreos.com"
INFO[0012]   Creating CustomResourceDefinition "operators.operators.coreos.com"
INFO[0012]   Creating CustomResourceDefinition "subscriptions.operators.coreos.com"
INFO[0012]   Creating Namespace "olm"
INFO[0012]   Creating Namespace "operators"
INFO[0012]   Creating ServiceAccount "olm/olm-operator-serviceaccount"
INFO[0012]   Creating ClusterRole "system:controller:operator-lifecycle-manager"
INFO[0012]   Creating ClusterRoleBinding "olm-operator-binding-olm"
INFO[0012]   Creating OLMConfig "cluster"
INFO[0015]   Creating Deployment "olm/olm-operator"
INFO[0015]   Creating Deployment "olm/catalog-operator"
INFO[0015]   Creating ClusterRole "aggregate-olm-edit"
INFO[0015]   Creating ClusterRole "aggregate-olm-view"
INFO[0015]   Creating OperatorGroup "operators/global-operators"
INFO[0015]   Creating OperatorGroup "olm/olm-operators"
INFO[0015]   Creating ClusterServiceVersion "olm/packageserver"
INFO[0015]   Creating CatalogSource "olm/operatorhubio-catalog"
INFO[0016] Waiting for deployment/olm-operator rollout to complete
INFO[0016]   Waiting for Deployment "olm/olm-operator" to rollout: 0 of 1 updated replicas are available
INFO[0019]   Deployment "olm/olm-operator" successfully rolled out
INFO[0019] Waiting for deployment/catalog-operator rollout to complete
INFO[0019]   Deployment "olm/catalog-operator" successfully rolled out
INFO[0019] Waiting for deployment/packageserver rollout to complete
INFO[0019]   Waiting for Deployment "olm/packageserver" to rollout: 0 of 2 updated replicas are available
INFO[0033]   Deployment "olm/packageserver" successfully rolled out
INFO[0033] Successfully installed OLM version "latest"

NAME                                            NAMESPACE    KIND                        STATUS
catalogsources.operators.coreos.com                          CustomResourceDefinition    Installed
clusterserviceversions.operators.coreos.com                  CustomResourceDefinition    Installed
installplans.operators.coreos.com                            CustomResourceDefinition    Installed
olmconfigs.operators.coreos.com                              CustomResourceDefinition    Installed
operatorconditions.operators.coreos.com                      CustomResourceDefinition    Installed
operatorgroups.operators.coreos.com                          CustomResourceDefinition    Installed
operators.operators.coreos.com                               CustomResourceDefinition    Installed
subscriptions.operators.coreos.com                           CustomResourceDefinition    Installed
olm                                                          Namespace                   Installed
operators                                                    Namespace                   Installed
olm-operator-serviceaccount                     olm          ServiceAccount              Installed
system:controller:operator-lifecycle-manager                 ClusterRole                 Installed
olm-operator-binding-olm                                     ClusterRoleBinding          Installed
cluster                                                      OLMConfig                   Installed
olm-operator                                    olm          Deployment                  Installed
catalog-operator                                olm          Deployment                  Installed
aggregate-olm-edit                                           ClusterRole                 Installed
aggregate-olm-view                                           ClusterRole                 Installed
global-operators                                operators    OperatorGroup               Installed
olm-operators                                   olm          OperatorGroup               Installed
packageserver                                   olm          ClusterServiceVersion       Installed
operatorhubio-catalog                           olm          CatalogSource               Installed

如上所示，OLM 会在 Kubernetes 集群中安装一堆的资源，可以看到 OLM 本身也包含了两个 Operator：OLM Operator 和 Catalog Operator。关于他们的作用可以参考 《如何管理越来越多的 operator？OLM 给你答案》 这篇文章。

OLM 通过 Bundle 形式来组织和管理 Operator，使用 make bundle 生成 Bundle 相关的配置文件：

$ make bundle IMG="aneasystone/memcached-operator:v0.0.1"
test -s ./memcached-operator/bin/controller-gen || GOBIN=./memcached-operator/bin go install sigs.k8s.io/controller-tools/cmd/controller-gen@v0.9.2
./memcached-operator/bin/controller-gen rbac:roleName=manager-role crd webhook paths="./..." output:crd:artifacts:config=config/crd/bases
test -s ./memcached-operator/bin/kustomize || { curl -s "https://raw.githubusercontent.com/kubernetes-sigs/kustomize/master/hack/install_kustomize.sh" | bash -s -- 3.8.7 ./memcached-operator/bin; }
operator-sdk generate kustomize manifests -q

Display name for the operator (required):
> memcached-operator

Description for the operator (required):
> memcached operator

Provider's name for the operator (required):
> aneasystone

Any relevant URL for the provider name (optional):
> https://www.aneasystone.com

Comma-separated list of keywords for your operator (required):
> memcached

Comma-separated list of maintainers and their emails (e.g. 'name1:email1, name2:email2') (required):
> aneasystone@gmail.com
cd config/manager && ./memcached-operator/bin/kustomize edit set image controller=aneasystone/memcached-operator:v0.0.1
./memcached-operator/bin/kustomize build config/manifests | operator-sdk generate bundle -q --overwrite --version 0.0.1
INFO[0001] Creating bundle.Dockerfile
INFO[0001] Creating bundle/metadata/annotations.yaml
INFO[0001] Bundle metadata generated suceessfully
operator-sdk bundle validate ./bundle
INFO[0001] All validation tests have completed successfully

然后将 Bundle 构建成镜像并推送到镜像仓库：

$ make bundle-build bundle-push BUNDLE_IMG="aneasystone/memcached-operator-bundle:v0.0.1"
docker build -f bundle.Dockerfile -t aneasystone/memcached-operator-bundle:v0.0.1 .
[+] Building 0.6s (7/7) FINISHED
 => [internal] load build definition from bundle.Dockerfile                                                            0.1s
 => => transferring dockerfile: 971B                                                                                   0.0s
 => [internal] load .dockerignore                                                                                      0.1s
 => => transferring context: 35B                                                                                       0.0s
 => [internal] load build context                                                                                      0.0s
 => => transferring context: 12.72kB                                                                                   0.0s
 => [1/3] COPY bundle/manifests /manifests/                                                                            0.0s
 => [2/3] COPY bundle/metadata /metadata/                                                                              0.1s
 => [3/3] COPY bundle/tests/scorecard /tests/scorecard/                                                                0.1s
 => exporting to image                                                                                                 0.1s
 => => exporting layers                                                                                                0.1s
 => => writing image sha256:849fde8bbc55db7a1cd884ccdc7c61bfdca343650f72eb65e616c98c17193bca                           0.0s
 => => naming to docker.io/aneasystone/memcached-operator-bundle:v0.0.1                                                0.0s
make docker-push IMG=aneasystone/memcached-operator-bundle:v0.0.1
make[1]: Entering directory './memcached-operator'
docker push aneasystone/memcached-operator-bundle:v0.0.1
The push refers to repository [docker.io/aneasystone/memcached-operator-bundle]
ee3ff18c6586: Pushed
1cca854eb4c8: Pushed
2fa3c5f0ef35: Pushed
v0.0.1: digest: sha256:c42ec3c4f9d461128c640f5568886b006e0332ea0d4a173008e97addefbfd3f9 size: 939
make[1]: Leaving directory './memcached-operator'

运行 Bundle 将我们的 Operator 部署到 Kubernetes 集群中：

$ operator-sdk run bundle docker.io/aneasystone/memcached-operator-bundle:v0.0.1
INFO[0023] Creating a File-Based Catalog of the bundle "docker.io/aneasystone/memcached-operator-bundle:v0.0.1"
INFO[0028] Generated a valid File-Based Catalog
INFO[0033] Created registry pod: docker-io-aneasystone-memcached-operator-bundle-v0-0-1
INFO[0033] Created CatalogSource: memcached-operator-catalog
INFO[0033] OperatorGroup "operator-sdk-og" created
INFO[0033] Created Subscription: memcached-operator-v0-0-1-sub
INFO[0037] Approved InstallPlan install-z264c for the Subscription: memcached-operator-v0-0-1-sub
INFO[0037] Waiting for ClusterServiceVersion "default/memcached-operator.v0.0.1" to reach 'Succeeded' phase
INFO[0037]   Waiting for ClusterServiceVersion "default/memcached-operator.v0.0.1" to appear
INFO[0056]   Found ClusterServiceVersion "default/memcached-operator.v0.0.1" phase: Pending
INFO[0058]   Found ClusterServiceVersion "default/memcached-operator.v0.0.1" phase: Installing
INFO[0069]   Found ClusterServiceVersion "default/memcached-operator.v0.0.1" phase: Succeeded
INFO[0069] OLM has successfully installed "memcached-operator.v0.0.1"

可以使用 kubectl get 检查 Operator 运行的状态，和上一节直接部署不一样的是，Operator 被安装在默认的 default 名字空间里了，其他的几乎没啥区别。可以更新 config/samples/cache_v1alpha1_memcached.yaml 文件来对 Operator 进行测试。

如果要卸载 Operator，执行下面的命令：

$ operator-sdk cleanup memcached-operator

卸载 OLM：

$ operator-sdk olm uninstall

使用 kubernetes-sigs/kubebuilder 开发 Operator

operator-sdk 和 kubebuilder 都是为了方便用户创建和管理 Operator 而生的脚手架项目，其实 operator-sdk 在底层也使用了 kubebuilder，比如 operator-sdk 的命令行工具就是直接调用 kubebuilder 的命令行工具。无论由 operator-sdk 还是 kubebuilder 创建的 Operator 项目都是调用的 controller-runtime 接口，具有相同的项目目录结构。

参考

1. Kubernetes 文档 / 概念 / 扩展 Kubernetes / Operator 模式
2. Kubernetes Operator 基础入门
3. Kubernetes Operator 快速入门教程
4. Kubernetes Operators 入门笔记
5. 亲历者说：Kubernetes API 与 Operator，不为人知的开发者战争
6. 《Kubernetes Operators eBook》By Jason Dobies & Joshua Wood
7. Quickstart for Go-based Operators
8. What is a Kubernetes operator?
9. Introducing Operators: Putting Operational Knowledge into Software
10. Kubernetes Operators 101, Part 1: Overview and key features
11. Kubernetes Operators 101, Part 2: How operators work
12. 如何管理越来越多的 operator？OLM 给你答案

更多

1. 安装 gcc 报 404 Not Found 错

在 Ubuntu 上使用 sudo apt install gcc 安装 gcc 时，报如下错误：

E: Failed to fetch http://security.ubuntu.com/ubuntu/pool/main/l/linux/linux-libc-dev_4.15.0-189.200_amd64.deb  404  Not Found [IP: 2001:67c:1562::15 80]
E: Unable to fetch some archives, maybe run apt-get update or try with --fix-missing?

解决方法很简单，执行 sudo apt update 更新软件源中的所有软件列表即可。

2. 使用 operator-sdk 创建 API 报错

执行 operator-sdk create api 命令创建 API 时，报如下错误：

/usr/local/go/src/net/cgo_linux.go:12:8: no such package located
Error: not all generators ran successfully
run `controller-gen object:headerFile=hack/boilerplate.go.txt paths=./... -w` to see all available markers, or `controller-gen object:headerFile=hack/boilerplate.go.txt paths=./... -h` for usage
Makefile:94: recipe for target 'generate' failed
make: *** [generate] Error 1
Error: failed to create API: unable to run post-scaffold tasks of "base.go.kubebuilder.io/v3": exit status 2

没有安装 gcc 工具，使用 sudo apt install gcc 安装 gcc 即可。

3. make build 或 make test 时报错

在公司电脑开发 Operator 时遇到了这个问题，执行 make build 或 make test 时报下面这样的错：

STEP: bootstrapping test environment
1.6621765789962418e+09  DEBUG   controller-runtime.test-env     starting control plane

1.6621765802518039e+09  ERROR   controller-runtime.test-env     unable to start the controlplane        {"tries": 0, "error": "timeout waiting for process etcd to start successfully (it may have failed to start, or stopped unexpectedly before becoming ready)"}

看报错信息猜测可能是和 etcd 有关，使用 ps aux | grep etcd 确实可以看到在执行测试时启动了一个 etcd 的进程：

$ ps aux | grep etcd
aneasystone  2609 23.0  0.1 737148 22560 pts/0    Sl   13:34   0:00 /home/aneasystone/.local/share/kubebuilder-envtest/k8s/1.24.1-linux-amd64/etcd --advertise-client-urls=http://127.0.0.1:52467 --data-dir=/tmp/k8s_test_framework_3831360890 --listen-client-urls=http://127.0.0.1:52467 --listen-peer-urls=http://127.0.0.1:52468 --unsafe-no-fsync=true

于是我试着手工运行这个命令，发现 etcd 服务启动时报错了：

2022-09-03 11:42:28.499748 E | etcdserver: publish error: etcdserver: request timed out
2022-09-03 11:42:35.501458 E | etcdserver: publish error: etcdserver: request timed out

使用 etcdctl 也连不上该 etcd 服务。一开始我以为是 kubebuilder 自带的 etcd 文件有问题，于是就自己安装了一个 etcd，直接运行时也是报错，只不过报错信息有点不一样：

panic: invalid page type: 0: 4

goroutine 1 [running]:

github.com/etcd-io/bbolt.(*Cursor).search(0xc00005be18, {0xc00005be70, 0x8, 0x8}, 0xc00005bdb8?)

看报错是位于 etcd-io/bbolt 这个包，BoltDB 是 etcd 使用的内存 KV 数据库。使用 bolt 和 panic: invalid page type 为关键字，很快就在 microsoft/WSL 里找到了一个相关的 Issue：BoltDB panics on cursor search since April update，根据 Issue 里的描述，写了一个 BoltDB 的简单示例：

package main

import (
    "fmt"
    "log"
    "os"

    "github.com/boltdb/bolt"
)

func main() {
    os.Remove("test.db")
    db, err := bolt.Open("test.db", 0600, nil)
    if err != nil {
        log.Fatal(err)
    }
    defer db.Close()

    db.Update(func(tx *bolt.Tx) error {
        _, err := tx.CreateBucket([]byte("MyBucket"))
        if err != nil {
            return fmt.Errorf("create bucket: %s", err)
        }
        return err
    })

    db.View(func(tx *bolt.Tx) error {
        b := tx.Bucket([]byte("MyBucket"))
        c := b.Cursor()
        c.Seek([]byte("test"))
        return nil
    })
    os.Remove("test.db")
}

运行代码后也是和上面几乎一模一样的报错：

$ go run main.go
panic: invalid page type: 0: 4

goroutine 1 [running]:
github.com/boltdb/bolt.(*Cursor).search(0xc00005be18, {0xc00005be70, 0x8, 0x8}, 0xc00005bdb8?)

至此大概可以推断这应该是 WSL 的问题，WSL 目前最新版本是 WSL 2，不过要注意的是，根据 Microsoft 官方的升级指南，WSL 2 只支持 Windows 10 Build 18362 之后的版本：

Builds lower than 18362 do not support WSL 2. Use the Windows Update Assistant to update your version of Windows.

打开 Windows 更新，更新完成后重启，问题解决。

4. Operator 示例

• Etcd Operator
• Prometheus Operator
• Operator SDK 官方示例
• 《Kubernetes Operators eBook》示例

微前端（Micro Frontends） 这个概念是在 2016 年底的时候在 ThoughtWorks Technology Radar 上首次提出来的，它将服务端的微服务概念延伸到前端领域。随着应用规模的不断变大，传说中的 SPA（单页面应用）会变得越来越复杂，也越来越难以维护。这样大规模的前端应用一般都是由很多相对独立的功能模块组合而成，且不同的功能模块由不同的团队负责，根据分而治之的思想，于是就有了将这些功能模块拆分成不同前端项目的想法，微前端技术也就此诞生。

qiankun 是阿里开源的一款微前端框架，它的灵感来自于 single-spa 项目，号称 可能是你见过最完善的微前端解决方案。single-spa 于 2018 年诞生，也是一个用于前端微服务化的解决方案，它实现了路由劫持和应用加载，不过它的缺点是不够灵活，不能动态加载 js 文件，而且没有处理样式隔离，不支持 js 沙箱机制。qiankun 于 2019 年开源，提供了更加开箱即用的 API (single-spa + sandbox + import-html-entry)，它基于 single-spa，具备 js 沙箱、样式隔离、HTML Loader、预加载 等微前端系统所需的能力。qiakun 升级 2.0 后，支持多个微应用的同时加载，有了这个特性，我们基本可以像接入 iframe 一样方便的接入微应用。

官方示例

qiankun 的源码里提供了大量完整的示例项目，我们先来体验体验这些示例，感受下微前端的魅力。首先，将 qiankun 的代码 clone 到本地：

$ git clone https://github.com/umijs/qiankun.git

qiankun 使用 Yarn 构建和打包项目，首先安装 Yarn：

$ npm install -g yarn

然后安装 qiankun 框架所依赖的包以及示例项目：

$ yarn install
$ yarn examples:install

示例项目中包含了各种不同框架的实现，比如 Vue、Vue 3、React 15、React 16、Angular 9 以及使用 jQuery 实现的纯 HTML 项目，Yarn 会依次安装各个示例项目的依赖包，整个过程会比较长，安装完成之后，使用下面的命令运行示例项目：

$ yarn examples:start

然后打开浏览器，访问 http://localhost:7099/：

或者使用下面的命令运行 multiple demo：

$ yarn examples:start-multiple

开发实战

这一节我们将从零开始，使用 qiankun 搭建一个简单的微前端项目，这个项目包括一个主应用和两个微应用。这里为了简单起见，两个微应用都是使用 Vue 开发，但是实际上，微前端对微应用的技术栈是不限的，微应用完全可以独立开发。

准备主应用

我们直接使用 vue-cli 创建一个 Vue 脚手架项目，首先确保已安装 Node.js 环境：

$ node -v
v16.14.2

$ npm -v
8.5.0

然后安装最新版本的 vue-cli：

$ npm install -g @vue/cli

$ vue -V
@vue/cli 5.0.8

使用 vue-cli 创建 demo 项目：

$ vue create demo

?  Your connection to the default npm registry seems to be slow.  
   Use https://registry.npmmirror.com for faster installation? Yes

Vue CLI v5.0.8
? Please pick a preset: Default ([Vue 3] babel, eslint)

Vue CLI v5.0.8
✨  Creating project in D:\code\weekly-practice\notes\week017-qiankun-micro-frontends\demo.
⚙️  Installing CLI plugins. This might take a while...

added 849 packages in 36s
🚀  Invoking generators...
📦  Installing additional dependencies...

added 95 packages in 11s
⚓  Running completion hooks...

📄  Generating README.md...

🎉  Successfully created project demo.      
👉  Get started with the following commands:

 $ cd demo
 $ npm run serve

使用 npm run serve 即可启动项目，启动成功后在浏览器中访问 http://localhost:8080/：

准备微应用

然后照葫芦画瓢，使用 vue-cli 创建 app1 和 app2 项目：

$ vue create app1

Vue CLI v5.0.8
? Please pick a preset: Default ([Vue 3] babel, eslint)
? Pick the package manager to use when installing dependencies: Yarn

Vue CLI v5.0.8
✨  Creating project in D:\code\weekly-practice\notes\week017-qiankun-micro-frontends\app1.
⚙️  Installing CLI plugins. This might take a while...

yarn install v1.22.19
info No lockfile found.
[1/4] Resolving packages...
[2/4] Fetching packages...
[3/4] Linking dependencies...

success Saved lockfile.
Done in 22.33s.
🚀  Invoking generators...
📦  Installing additional dependencies...

yarn install v1.22.19
[1/4] Resolving packages...
[2/4] Fetching packages...
[3/4] Linking dependencies...
[4/4] Building fresh packages...
success Saved lockfile.
Done in 7.88s.
⚓  Running completion hooks...

📄  Generating README.md...

🎉  Successfully created project app1.
👉  Get started with the following commands:

 $ cd app1
 $ yarn serve

使用 vue-cli 创建的项目默认端口是 8080，为了不和主应用冲突，需要修改 vue.config.js 配置文件，将微应用的端口修改为 8081 和 8082：

const { defineConfig } = require('@vue/cli-service')
module.exports = defineConfig({
  transpileDependencies: true,
  devServer: {
    port: 8081
  }
})

改造主应用

一切准备就绪后，接下来我们就开始将主应用改造成微前端架构。首先在主应用安装 qiankun 依赖：

$ npm i qiankun -S

然后在 main.js 文件中注册微应用：

import { registerMicroApps, start } from 'qiankun';

registerMicroApps([{
  name: 'app1',
  entry: '//localhost:8081',
  container: '#app1',
  activeRule: '/app1'
}, {
  name: 'app2',
  entry: '//localhost:8082',
  container: '#app2',
  activeRule: '/app2'
}]);

start();

只需这几行代码，微应用就注册好了。当 url 发生变化时，qiankun 会根据 activeRule 规则自动匹配相应的微应用，并将其插入到指定的 DOM 容器（container）中。我们在 public/index.html 里为每个微应用准备一个容器：

    <div id="app"></div>
    <div id="app1"></div>
    <div id="app2"></div>

改造微应用

不过此时主应用还无法加载微应用，我们需要对微应用做两处改造。首先，微应用需要在自己的入口 js (通常就是你配置的 webpack 的 entry js) 导出 bootstrap、mount 和 unmount 三个生命周期钩子，以供主应用在适当的时机调用。打开文件 main.js，添加如下代码：

let instance = null
function render() {
  instance = createApp(App).mount('#app')
}

if (!window.__POWERED_BY_QIANKUN__) { // 默认独立运行
  render();
}

export async function bootstrap(props) {
  console.log('bootstrap app1', props)
}
export async function mount(props) {
  console.log('mount app1', props)
  render()
}
export async function unmount(props) {
  console.log('unmount app1', props)
  console.log(instance)
}

其中我们可以通过 window.__POWERED_BY_QIANKUN__ 来区分微应用是自启动的还是由 qiankun 加载的，这样可以让微应用在两种模式下都兼容。

注意，网上有很多示例在 unmount 中会调用 instance.$destroy() 来销毁实例，但是在 Vue 3 中 instance.$destroy() 方法已经废弃了。

其次，我们需要将微应用改为以 umd 的方式打包，并注意设置 'Access-Control-Allow-Origin':'*' 允许跨域访问：

const { defineConfig } = require('@vue/cli-service')
module.exports = defineConfig({
  transpileDependencies: true,
  devServer: {
    port: 8081,
    headers:{
      'Access-Control-Allow-Origin':'*'
    }
  },
  configureWebpack:{
    output:{
      library: `app1`,
      libraryTarget: 'umd'
    }
  }
})

运行

主应用和微应用都改造完成后，依次运行，然后在浏览器中依次访问，确保每个应用都可独立访问。另外，由于我们在主应用中加载了微应用，使用 http://localhost:8080/app1 和 http://localhost:8080/app2 应该也可以访问微应用：

使用 Vue Router 切换微应用

为了更方便地构建单页面应用（SPA），在现代的 Web 框架中，几乎都有 路由 的概念，一般用在左侧菜单或顶部导航上。Vue Router 就是 Vue.js 的官方路由。首先在主应用中安装 vue-router 和 element-plus：

$ npm i vue-router -S
$ npm i element-plus -S

在 main.js 中注册路由：

import { createRouter, createWebHistory } from 'vue-router'
import HelloWorld from './components/HelloWorld.vue'
import About from './components/About.vue'

const router = createRouter({
  history: createWebHistory(),
  routes: [
    { path: '/hello', component: HelloWorld },
    { path: '/about', component: About }
  ]
})

import ElementPlus from 'element-plus'
import 'element-plus/dist/index.css'

createApp(App).use(router).use(ElementPlus).mount('#app')

主应用的代码修改如下：

<template>
  <div>
    <h1>Hello qiankun!</h1>
    <el-menu :router="true" mode="horizontal">
      <el-menu-item index="/hello">Hello</el-menu-item>
      <el-menu-item index="/about">About</el-menu-item>
      <el-menu-item index="/app1">App1</el-menu-item>
      <el-menu-item index="/app2">App2</el-menu-item>
    </el-menu>
    <router-view></router-view>
    <div id="app1"></div>
    <div id="app2"></div>
  </div>
</template>

为什么切换微应用时，导航消失了？而不是加载在导航下面的容器中？

这是因为主应用的容器 id 和 微应用的容器 id 都叫 app，所以冲突了，将主应用的 id 修改为 demo 即可。

运行之后，在浏览器里访问主应用，然后就可以通过导航菜单来访问微应用了：

参考

1. qiankun 官方文档
2. qiankun 技术圆桌 | 分享一些 qiankun 开发及微前端实践过程中的心得
3. 万字长文-落地微前端 qiankun 理论与实践指北
4. Micro Frontends | extending the microservice idea to frontend development
5. single-spa
6. 微前端框架 之 single-spa 从入门到精通
7. 微前端框架 之 qiankun 从入门到源码分析
8. 微前端实战 - 基于 qiankun 的最佳实践

Spring Boot 官网将 Actuator 称为 生产就绪特性（Production-ready features），它提供了诸如健康检查、审计、指标收集、HTTP 跟踪等功能，帮助我们监控和管理 Spring Boot 应用。

快速开始

使用 Spring Initializr 创建一个项目，依赖项选择 Web 和 Actuator，或者在已有项目中添加依赖：

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-actuator</artifactId>
</dependency>

启动程序后，就能访问 /actuator 接口了：

$ curl -s http://localhost:8080/actuator | jq
{
  "_links": {
    "self": {
      "href": "http://localhost:8080/actuator",
      "templated": false
    },
    "health": {
      "href": "http://localhost:8080/actuator/health",
      "templated": false
    },
    "health-path": {
      "href": "http://localhost:8080/actuator/health/{*path}",
      "templated": true
    }
  }
}

Spring Boot Actuator 提供了很多有用的接口，被称为端点（Endpoints），访问 /actuator 就可以看出程序当前暴露了哪些端点。端点的访问路径可以通过下面的配置修改：

management.endpoints.web.base-path=/management

从上面的命令结果可以看出在最新版本中，Actuator 只暴露一个 /health 端点，这个端点提供了关于应用健康情况的一些基础信息。

如果要开启所有端点，可以打开配置文件 application.properties，添加如下配置项：

management.endpoints.web.exposure.include=*

现在看看暴露了哪些端点：

$ curl -s http://localhost:8080/actuator | jq
{
  "_links": {
    "self": {
      "href": "http://localhost:8080/actuator",
      "templated": false
    },
    "beans": {
      "href": "http://localhost:8080/actuator/beans",
      "templated": false
    },
    "caches-cache": {
      "href": "http://localhost:8080/actuator/caches/{cache}",
      "templated": true
    },
    "caches": {
      "href": "http://localhost:8080/actuator/caches",
      "templated": false
    },
    "health": {
      "href": "http://localhost:8080/actuator/health",
      "templated": false
    },
    "health-path": {
      "href": "http://localhost:8080/actuator/health/{*path}",
      "templated": true
    },
    "info": {
      "href": "http://localhost:8080/actuator/info",
      "templated": false
    },
    "conditions": {
      "href": "http://localhost:8080/actuator/conditions",
      "templated": false
    },
    "configprops": {
      "href": "http://localhost:8080/actuator/configprops",
      "templated": false
    },
    "configprops-prefix": {
      "href": "http://localhost:8080/actuator/configprops/{prefix}",
      "templated": true
    },
    "env": {
      "href": "http://localhost:8080/actuator/env",
      "templated": false
    },
    "env-toMatch": {
      "href": "http://localhost:8080/actuator/env/{toMatch}",
      "templated": true
    },
    "loggers": {
      "href": "http://localhost:8080/actuator/loggers",
      "templated": false
    },
    "loggers-name": {
      "href": "http://localhost:8080/actuator/loggers/{name}",
      "templated": true
    },
    "heapdump": {
      "href": "http://localhost:8080/actuator/heapdump",
      "templated": false
    },
    "threaddump": {
      "href": "http://localhost:8080/actuator/threaddump",
      "templated": false
    },
    "metrics-requiredMetricName": {
      "href": "http://localhost:8080/actuator/metrics/{requiredMetricName}",
      "templated": true
    },
    "metrics": {
      "href": "http://localhost:8080/actuator/metrics",
      "templated": false
    },
    "scheduledtasks": {
      "href": "http://localhost:8080/actuator/scheduledtasks",
      "templated": false
    },
    "mappings": {
      "href": "http://localhost:8080/actuator/mappings",
      "templated": false
    }
  }
}

其中 * 表示开启所有端点，也可以只开启部分端点：

management.endpoints.web.exposure.include=beans,health,info

或者选择性的关闭部分端点：

management.endpoints.web.exposure.exclude=beans,info

原生端点解析

Spring Boot Actuator 暴露的原生端点大概可以分成三大类：

• 应用配置类：获取应用程序中加载的应用配置、环境变量、自动化配置报告等与Spring Boot应用密切相关的配置类信息。
• 度量指标类：获取应用程序运行过程中用于监控的度量指标，比如：内存信息、线程池信息、HTTP请求统计等。
• 操作控制类：提供了对应用的关闭等操作类功能。

下面对 Actuator 暴露的原生端点依次体验和学习。

Beans (beans)

端点 /beans 列出了应用程序中所有 Bean 的信息，包括 Bean 的名称、别名、类型、是否单例、依赖等等。

$ curl -s http://localhost:8080/actuator/beans | jq
{
  "contexts": {
    "application": {
      "beans": {
        "endpointCachingOperationInvokerAdvisor": {
          "aliases": [],
          "scope": "singleton",
          "type": "org.springframework.boot.actuate.endpoint.invoker.cache.CachingOperationInvokerAdvisor",
          "resource": "class path resource [org/springframework/boot/actuate/autoconfigure/endpoint/EndpointAutoConfiguration.class]",
          "dependencies": [
            "org.springframework.boot.actuate.autoconfigure.endpoint.EndpointAutoConfiguration",
            "environment"
          ]
        },
        "defaultServletHandlerMapping": {
          "aliases": [],
          "scope": "singleton",
          "type": "org.springframework.web.servlet.HandlerMapping",
          "resource": "class path resource [org/springframework/boot/autoconfigure/web/servlet/WebMvcAutoConfiguration$EnableWebMvcConfiguration.class]",
          "dependencies": [
            "org.springframework.boot.autoconfigure.web.servlet.WebMvcAutoConfiguration$EnableWebMvcConfiguration"
          ]
        },
        ...
      },
      "parentId": null
    }
  }
}

Spring Boot 自身会创建很多个 Bean，这里是完整的结果。

Health (health)

/health 端点用来检查应用程序的健康情况，默认情况下它只会显示应用程序的状态为 UP 或 DOWN：

$ curl -s http://localhost:8080/actuator/health | jq
{
  "status": "UP"
}

通过 management.endpoint.health.show-details 配置可以控制接口返回的内容：

我们将其设置为 always：

management.endpoint.health.show-details=always

此时接口返回内容如下：

$ curl -s http://localhost:8080/actuator/health | jq
{
  "status": "UP",
  "components": {
    "diskSpace": {
      "status": "UP",
      "details": {
        "total": 174500155392,
        "free": 34697940992,
        "threshold": 10485760,
        "exists": true
      }
    },
    "ping": {
      "status": "UP"
    }
  }
}

由于我这个只是一个 Demo 项目，没有其他的依赖组件，所以健康状态的详情信息有点少。可以在 pom.xml 中添加一个 Mongo 的依赖：

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-data-mongodb</artifactId>
</dependency>

此时再查看 /health 端点，详情里就多个 Mongo 的信息了：

$ curl -s http://localhost:8080/actuator/health | jq
{
  "status": "UP",
  "components": {
    "diskSpace": {
      "status": "UP",
      "details": {
        "total": 174500155392,
        "free": 34691891200,
        "threshold": 10485760,
        "exists": true
      }
    },
    "mongo": {
      "status": "UP",
      "details": {
        "version": "4.0.27"
      }
    },
    "ping": {
      "status": "UP"
    }
  }
}

我们将 Mongo 服务手工停掉，再访问 /health 端点，可以看出，尽管我们的服务还是运行着的，但是我们服务的健康状态已经是 DOWN 了：

$ curl -s http://localhost:8080/actuator/health | jq
{
  "status": "DOWN",
  "components": {
    "diskSpace": {
      "status": "UP",
      "details": {
        "total": 174500155392,
        "free": 34691891200,
        "threshold": 10485760,
        "exists": true
      }
    },
    "mongo": {
      "status": "DOWN",
      "details": {
        "error": "org.springframework.dao.DataAccessResourceFailureException: Timed out after 30000 ms while waiting to connect. Client view of cluster state is {type=UNKNOWN, servers=[{address=localhost:27017, type=UNKNOWN, state=CONNECTING, exception={com.mongodb.MongoSocketOpenException: Exception opening socket}, caused by {java.net.ConnectException: Connection refused: connect}}]; nested exception is com.mongodb.MongoTimeoutException: Timed out after 30000 ms while waiting to connect. Client view of cluster state is {type=UNKNOWN, servers=[{address=localhost:27017, type=UNKNOWN, state=CONNECTING, exception={com.mongodb.MongoSocketOpenException: Exception opening socket}, caused by {java.net.ConnectException: Connection refused: connect}}]"
      }
    },
    "ping": {
      "status": "UP"
    }
  }
}

健康指示器（HealthIndicator）

Spring Boot Actuator 提供了很多自动配置的 健康指示器（HealthIndicator），当你的项目依赖某个组件的时候，该组件对应的健康指示器就会被自动装配，继而采集对应的信息。比如上面我们添加 Mongo 依赖后，MongoHealthIndicator 就会自动被用来采集 Mongo 的信息。

每个健康指示器都有一个 key，默认是指示器的 Bean 名称去掉 HealthIndicator 后缀，比如 Mongo 的健康指示器就是 mongo。可以使用 management.health.<key>.enabled 配置关闭某个指示器。可以通过下面这个配置关闭 Mongo 的健康检查：

management.health.mongo.enabled=false

常见的健康指示器和对应的 key 如下：

可以通过下面这个配置关闭上面列表中的所有健康检查：

management.health.defaults.enabled=false

为了适应 Kubernetes 环境，Spring Boot Actuator 还提供了下面两个健康指示器，默认关闭。分别对应 Kubernetes 里的 Liveness 和 Readiness 探针，参考 Kubernetes 官方文档。

自定义健康指示器

当 Actuator 自带的健康指示器不能满足我们需求时，我们也可以自定义一个健康指示器，只需要实现 HealthIndicator 接口或者继承AbstractHealthIndicator 类即可，下面是一个简单的示例：

/**
 * 自定义健康指示器
 */
@Component
public class TestHealthIndicator extends AbstractHealthIndicator {

    @Override
    protected void doHealthCheck(Builder builder) throws Exception {
        builder.up()
            .withDetail("app", "test")
            .withDetail("error", 0);
    }

}

withDetail 用于显示健康详情，如果要显示状态 DOWN，就抛出一个异常即可。此时的健康详情接口返回如下：

$ curl -s http://localhost:8080/actuator/health | jq
{
  "status": "UP",
  "components": {
    "diskSpace": {
      "status": "UP",
      "details": {
        "total": 174500155392,
        "free": 34691883008,
        "threshold": 10485760,
        "exists": true
      }
    },
    "ping": {
      "status": "UP"
    },
    "test": {
      "status": "UP",
      "details": {
        "app": "test",
        "error": 0
      }
    }
  }
}

Info (info)

/info 端点用于展示应用程序的一些基本信息，默认情况下 /info 返回的是一个空 JSON。

$ curl -s http://localhost:8080/actuator/info | jq
{}

Actuator 支持多种信息的收集方式，不过默认都是关闭的，需要使用 management.info.<id>.enabled 手动开启。支持的信息有如下几种：

显示构建信息

如果想在 /info 端点中显示项目的构建信息，我们需要在项目中生成 META-INF/build-info.properties 文件。这个文件可以使用 spring-boot-maven-plugin 自动生成，只需要在插件配置中添加一个 build-info 的 goal 即可：

<build>
  <plugins>
    <plugin>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-maven-plugin</artifactId>
      <executions>
        <execution>
          <goals>
            <goal>build-info</goal>
          </goals>
        </execution>
      </executions>
    </plugin>
  </plugins>
</build>

重新构建并运行程序，再访问 /info 端点：

$ curl -s http://localhost:8080/actuator/info | jq
{
  "build": {
    "artifact": "demo",
    "name": "demo",
    "time": "2022-07-04T23:04:34.085Z",
    "version": "0.0.1-SNAPSHOT",
    "group": "com.example"
  }
}

显示环境配置

这个配置默认是关闭的，需要在配置文件中开启：

management.info.env.enabled=true

开启之后就可以在配置文件中添加 info. 开头的配置了。如果你使用的是 Maven 构建工具，你还可以在配置中使用 @...@ 来引用 Maven 的配置，这被称为 Maven 的自动配置展开：

info.env.app.name=demo
info.env.app.encoding=@project.build.sourceEncoding@
info.env.app.java.source=@java.version@
info.env.app.java.target=@java.version@

你还可以在程序启动时，使用 -- 动态地注入配置：

$ java -jar .\target\demo-0.0.1-SNAPSHOT.jar --info.env.app.name=demo

查看 /info 端点的结果如下：

$ curl -s http://localhost:8080/actuator/info | jq
{
  "env": {
    "app": {
      "name": "demo",
      "encoding": "UTF-8",
      "java": {
        "source": "17.0.3",
        "target": "17.0.3"
      }
    }
  }
}

显示 Git 信息

/info 端点还可以显示 Git 的一些基本信息，只要在你的项目中包含了 git.properties 文件即可。这个文件可以通过 git-commit-id-maven-plugin 插件生成：

<build>
    <plugins>
        <plugin>
            <groupId>pl.project13.maven</groupId>
            <artifactId>git-commit-id-plugin</artifactId>
        </plugin>
    </plugins>
</build>

使用 /info 端点查看 Git 信息如下：

$ curl -s http://localhost:8080/actuator/info | jq
{
  "git": {
    "branch": "main",
    "commit": {
      "id": "61e8bd9",
      "time": "2022-07-04T00:12:32Z"
    }
  }
}

显示 Java 运行时信息

这个配置默认是关闭的，通过下面的配置开启：

management.info.java.enabled=true

查看 /info 端点的结果如下：

$ curl -s http://localhost:8080/actuator/info | jq
{
  "java": {
    "version": "11.0.8",
    "vendor": {
      "name": "Oracle Corporation",
      "version": "18.9"
    },
    "runtime": {
      "name": "Java(TM) SE Runtime Environment",
      "version": "11.0.8+10-LTS"
    },
    "jvm": {
      "name": "Java HotSpot(TM) 64-Bit Server VM",
      "vendor": "Oracle Corporation",
      "version": "11.0.8+10-LTS"
    }
  }
}

显示操作系统信息

这个配置默认是关闭的，通过下面的配置开启：

management.info.os.enabled=true

查看 /info 端点的结果如下：

$ curl -s http://localhost:8080/actuator/info | jq
{
  "os": {
    "name": "Windows 10",
    "version": "10.0",
    "arch": "amd64"
  }
}

自定义信息

Spring Boot Actuator 通过在 ApplicationContext 中查找所有实现了 InfoContributor 接口的 Bean 来收集应用信息，譬如上面介绍的几种应用信息分别是通过 BuildInfoContributor、EnvironmentInfoContributor、GitInfoContributor、JavaInfoContributor 和 OsInfoContributor 实现的。我们也可以自己实现 InfoContributor 接口，来暴露自定义的应用信息。下面是一个简单的示例：

@Component
public class TestInfoContributor implements InfoContributor {

    @Override
    public void contribute(Builder builder) {
        builder.withDetail("hello", "world");
    }
    
}

此时查看 /info 端点，可以看到下面的结果：

$ curl -s http://localhost:8080/actuator/info | jq
{
  "hello": "world"
}

Conditions Evaluation Report (conditions)

Spring Boot 使用 约定优于配置 的理念，采用包扫描和自动化配置的机制来加载依赖程序中的 Spring Bean。虽然这样做能让我们的代码变得非常简洁，但是整个应用的实例创建和依赖关系等信息都被离散到了各个配置类的注解上，这使得我们分析整个应用中资源和实例的各种关系变得非常的困难。

/conditions 端点可以用于排查程序中的配置类（@Configuration）或自动化配置类（@AutoConfiguration）是否生效的情况：

$ curl -s http://localhost:8080/actuator/conditions | jq
{
  "contexts": {
    "application": {
      "positiveMatches": {
        "AuditEventsEndpointAutoConfiguration": [
          {
            "condition": "OnAvailableEndpointCondition",
            "message": "@ConditionalOnAvailableEndpoint marked as exposed by a 'management.endpoints.jmx.exposure' property"
          }
        ],
        ...
      },
      "negativeMatches": {
        "RabbitHealthContributorAutoConfiguration": {
          "notMatched": [
            {
              "condition": "OnClassCondition",
              "message": "@ConditionalOnClass did not find required class 'org.springframework.amqp.rabbit.core.RabbitTemplate'"
            }
          ],
          "matched": []
        },
        ...
      },
      "unconditionalClasses": [
        "org.springframework.boot.autoconfigure.context.ConfigurationPropertiesAutoConfiguration",
        "org.springframework.boot.actuate.autoconfigure.availability.AvailabilityHealthContributorAutoConfiguration",
        "org.springframework.boot.actuate.autoconfigure.info.InfoContributorAutoConfiguration",
        "org.springframework.boot.autoconfigure.context.PropertyPlaceholderAutoConfiguration",
        "org.springframework.boot.autoconfigure.context.LifecycleAutoConfiguration",
        "org.springframework.boot.actuate.autoconfigure.health.HealthContributorAutoConfiguration",
        "org.springframework.boot.actuate.autoconfigure.metrics.integration.IntegrationMetricsAutoConfiguration",
        "org.springframework.boot.actuate.autoconfigure.endpoint.EndpointAutoConfiguration",
        "org.springframework.boot.autoconfigure.availability.ApplicationAvailabilityAutoConfiguration",
        "org.springframework.boot.autoconfigure.info.ProjectInfoAutoConfiguration",
        "org.springframework.boot.actuate.autoconfigure.web.server.ManagementContextAutoConfiguration"
      ]
    }
  }
}

返回结果较大，完整的返回结果在这里。

返回结果里包括三大部分：positiveMatches 表示哪些配置条件是满足的，negativeMatches 表示哪些配置条件是不满足的，而 unconditionalClasses 表示无条件的配置类，这些配置无需满足什么条件就会自动加载。

Configuration Properties (configprops)

@ConfigurationProperties 是 Spring Boot 提供的读取配置文件的一个注解，它可以将 application.properties 配置文件中的值注入到 Bean 对象上。/configprops 端点用于显示程序中所有的 @ConfigurationProperties Bean 以及配置值（包括默认值）：

$ curl -s http://localhost:8080/actuator/configprops | jq
{
  "contexts": {
    "application": {
      "beans": {
        "management.endpoints.web-org.springframework.boot.actuate.autoconfigure.endpoint.web.WebEndpointProperties": {
          "prefix": "management.endpoints.web",
          "properties": {
            "pathMapping": {},
            "exposure": {
              "include": [
                "*"
              ],
              "exclude": []
            },
            "basePath": "/actuator",
            "discovery": {
              "enabled": true
            }
          },
          "inputs": {
            "pathMapping": {},
            "exposure": {
              "include": [
                {
                  "value": "*",
                  "origin": "class path resource [application.properties] - 2:43"
                }
              ],
              "exclude": []
            },
            "basePath": {},
            "discovery": {
              "enabled": {}
            }
          }
        },
        ...
      },
      "parentId": null
    }
  }
}

返回结果较大，完整的返回结果在这里。

从上面的结果可以看出，我们在配置文件中配置的 management.endpoints.web.exposure.include=* 实际上就对应的 org.springframework.boot.actuate.autoconfigure.endpoint.web.WebEndpointProperties 这个配置类里的属性。

Environment (env)

/env 端点用于展示应用程序的环境变量配置。Spring Boot 中的环境变量配置不仅包括了操作系统中的环境变量，而且还包括了配置文件中的配置，以及命令行中配置等。返回结果较大，这里是完整结果。

$ curl -s http://localhost:8080/actuator/env | jq
{
  "activeProfiles": [],
  "propertySources": [
    {
      "name": "server.ports",
      "properties": {
        "local.server.port": {
          "value": 8080
        }
      }
    },
    {
      "name": "servletContextInitParams",
      "properties": {}
    },
    {
      "name": "systemProperties",
      "properties": {
        "sun.desktop": {
          "value": "windows"
        },
        ...
      }
    },
    {
      "name": "systemEnvironment",
      "properties": {
        "USERDOMAIN_ROAMINGPROFILE": {
          "value": "DESKTOP-CH85E4K",
          "origin": "System Environment Property \"USERDOMAIN_ROAMINGPROFILE\""
        },
        ...
      }
    },
    {
      "name": "Config resource 'class path resource [application.properties]' via location 'optional:classpath:/'",
      "properties": {
        "management.endpoints.web.exposure.include": {
          "value": "*",
          "origin": "class path resource [application.properties] - 2:43"
        },
        ...
      }
    }
  ]
}

Loggers (loggers)

/loggers 端点不仅可以查询我们在应用程序中所设置的日志等级，而且可以通过接口动态地进行修改，这在排查问题时非常有用。

下面是 /loggers 端点返回的部分结果：

$ curl -s http://localhost:8080/actuator/loggers | jq
{
  "levels": [
    "OFF",
    "ERROR",
    "WARN",
    "INFO",
    "DEBUG",
    "TRACE"
  ],
  "loggers": {
    "ROOT": {
      "configuredLevel": "INFO",
      "effectiveLevel": "INFO"
    },
    "com": {
      "configuredLevel": null,
      "effectiveLevel": "INFO"
    },
    "com.example": {
      "configuredLevel": null,
      "effectiveLevel": "INFO"
    },
    "com.example.demo": {
      "configuredLevel": null,
      "effectiveLevel": "INFO"
    },
    "com.example.demo.DemoApplication": {
      "configuredLevel": null,
      "effectiveLevel": "INFO"
    },
    "com.example.demo.TestHealthIndicator": {
      "configuredLevel": null,
      "effectiveLevel": "INFO"
    },
    ...
  },
  "groups": {
    "web": {
      "configuredLevel": null,
      "members": [
        "org.springframework.core.codec",
        "org.springframework.http",
        "org.springframework.web",
        "org.springframework.boot.actuate.endpoint.web",
        "org.springframework.boot.web.servlet.ServletContextInitializerBeans"
      ]
    },
    "sql": {
      "configuredLevel": null,
      "members": [
        "org.springframework.jdbc.core",
        "org.hibernate.SQL",
        "org.jooq.tools.LoggerListener"
      ]
    }
  }
}

也可以单独访问一个 logger：

$ curl -s http://localhost:8080/actuator/loggers/com.example.demo | jq
{
  "configuredLevel": null,
  "effectiveLevel": "INFO"
}

还可以使用 POST 请求来修改这个 logger 的日志等级，比如下面是一个例子，将 com.example.demo 的日志等级改为 DEBUG：

$ curl -s -X POST -d '{"configuredLevel": "DEBUG"}' \
  -H "Content-Type: application/json" \
  http://localhost:8080/actuator/loggers/com.example.demo

如果在生产环境中，你想要打印一些 DEBUG 信息用于诊断程序的一些异常情况，你只需要使用这个方法修改日志等级，而不需要重启应用。如果想重置日志等级，将 configuredLevel 设置为 null 即可：

$ curl -s -X POST -d '{"configuredLevel": null}' \
  -H "Content-Type: application/json" \
  http://localhost:8080/actuator/loggers/com.example.demo

Heap Dump (heapdump)

访问 /heapdump 端点会自动生成一个 JVM 堆文件。

$ curl -O http://localhost:8080/actuator/heapdump
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100 30.9M  100 30.9M    0     0  85.5M      0 --:--:-- --:--:-- --:--:-- 85.5M

这个堆文件的格式取决于你所使用的 JVM，比如 HotSpot JVM 的 HPROF 格式，或者 OpenJ9 的 PHD 格式。我们可以使用 VisualVM 或 Memory Analyzer（MAT） 等工具打开这个文件对内存进行分析。

Thread Dump (threaddump)

/threaddump 端点用于查看应用程序的所有线程情况，方便我们在日常工作中定位问题。主要展示了线程名、线程ID、线程状态、是否等待锁资源、线程堆栈等信息。

$ curl -s http://localhost:8080/actuator/threaddump | jq
{
  "threads": [
    {
      "threadName": "Reference Handler",
      "threadId": 2,
      "blockedTime": -1,
      "blockedCount": 3,
      "waitedTime": -1,
      "waitedCount": 0,
      "lockName": null,
      "lockOwnerId": -1,
      "lockOwnerName": null,
      "daemon": true,
      "inNative": false,
      "suspended": false,
      "threadState": "RUNNABLE",
      "priority": 10,
      "stackTrace": [
        {
          "classLoaderName": null,
          "moduleName": "java.base",
          "moduleVersion": "11.0.8",
          "methodName": "waitForReferencePendingList",
          "fileName": "Reference.java",
          "lineNumber": -2,
          "className": "java.lang.ref.Reference",
          "nativeMethod": true
        },
        {
          "classLoaderName": null,
          "moduleName": "java.base",
          "moduleVersion": "11.0.8",
          "methodName": "processPendingReferences",
          "fileName": "Reference.java",
          "lineNumber": 241,
          "className": "java.lang.ref.Reference",
          "nativeMethod": false
        },
        {
          "classLoaderName": null,
          "moduleName": "java.base",
          "moduleVersion": "11.0.8",
          "methodName": "run",
          "fileName": "Reference.java",
          "lineNumber": 213,
          "className": "java.lang.ref.Reference$ReferenceHandler",
          "nativeMethod": false
        }
      ],
      "lockedMonitors": [],
      "lockedSynchronizers": [],
      "lockInfo": null
    },
    ...
  ]
}

这里只显示了部分结果，完整的结果在这里。

默认情况下，该端点的返回结果是 JSON 格式的，这对于程序来说比较友好，比如我们想开发一个线程分析程序，通过调用该接口就能拿到结构化的线程信息。不过这个格式看起来不太直观，如果返回的结果能和 jstack 的输出格式一样就好了，当然 Actuator 的开发人员也想到了这一点，实现起来也非常简单，只要在请求中加上 Accept: text/plain 头即可：

$ curl -s http://localhost:8080/actuator/threaddump -H 'Accept: text/plain'

Metrics (metrics)

Spring Boot Actuator 使用 Micrometer 来收集指标，收集的指标可以通过 /metrics 端点来查询，比如：JVM 内存、线程、垃圾回收、Tomcat 会话、CPU、进程等信息。

$ curl -s http://localhost:8080/actuator/metrics | jq
{
  "names": [
    "application.ready.time",
    "application.started.time",
    "disk.free",
    "disk.total",
    "executor.active",
    "executor.completed",
    "executor.pool.core",
    "executor.pool.max",
    "executor.pool.size",
    "executor.queue.remaining",
    "executor.queued",
    "http.server.requests",
    "jvm.buffer.count",
    "jvm.buffer.memory.used",
    "jvm.buffer.total.capacity",
    "jvm.classes.loaded",
    "jvm.classes.unloaded",
    "jvm.gc.live.data.size",
    "jvm.gc.max.data.size",
    "jvm.gc.memory.allocated",
    "jvm.gc.memory.promoted",
    "jvm.gc.overhead",
    "jvm.gc.pause",
    "jvm.memory.committed",
    "jvm.memory.max",
    "jvm.memory.usage.after.gc",
    "jvm.memory.used",
    "jvm.threads.daemon",
    "jvm.threads.live",
    "jvm.threads.peak",
    "jvm.threads.states",
    "logback.events",
    "process.cpu.usage",
    "process.start.time",
    "process.uptime",
    "system.cpu.count",
    "system.cpu.usage",
    "tomcat.sessions.active.current",
    "tomcat.sessions.active.max",
    "tomcat.sessions.alive.max",
    "tomcat.sessions.created",
    "tomcat.sessions.expired",
    "tomcat.sessions.rejected"
  ]
}

直接访问地址 /actuator/metrics 时，返回的只有指标名称，为了获取指标详情，需要在地址后面再加上指标名称，比如下面是查看应用的 process.cpu.usage 指标：

$ curl -s http://localhost:8080/actuator/metrics/process.cpu.usage | jq
{
  "name": "process.cpu.usage",
  "description": "The \"recent cpu usage\" for the Java Virtual Machine process",
  "baseUnit": null,
  "measurements": [
    {
      "statistic": "VALUE",
      "value": 0.151430864178387
    }
  ],
  "availableTags": []
}

监控系统一览

Actuator 不仅可以将指标通过 /metrics 端点暴露出来，而且还可以将指标转换成各种不同的监控系统的格式，集成不同的监控系统，实现监控和告警功能。集成方式很简单，只需要在 pom.xml 中添加 micrometer-registry-{system} 依赖即可，比如要集成 Promethues 监控，我们可以添加如下依赖：

<dependency>
    <groupId>io.micrometer</groupId>
    <artifactId>micrometer-registry-prometheus</artifactId>
</dependency>

Actuator 支持的监控系统如下：

• AppOptics
• Atlas
• Datadog
• Dynatrace
• Elastic
• Ganglia
• Graphite
• Humio
• Influx
• JMX
• KairosDB
• New Relic
• Prometheus
• SignalFx
• Stackdriver
• StatsD
• Wavefront

具体配置可以参考 Micrometer 或 Actuator 的官方文档。

自定义指标

Micrometer 提供了一个 MeterRegistry 类，用于实现自定义指标。下面的例子定义了一个名叫 hello.counter 的计数器指标，并带有 app=demo 的 Tag，每当访问一次 /hello 页面，计数器就会加一：

@RestController
public class DemoController {

    private final MeterRegistry registry;
    public DemoController(MeterRegistry registry) {
        this.registry = registry;
    }

    @GetMapping("/hello")
    public String hello() {
        this.registry.counter("hello.counter", Tags.of("app", "demo")).increment();
        return "hello";
    }
}

访问一次 /hello 接口之后，然后再访问 /actuator/metrics/hello.counter，可以看到这个指标的信息：

$ curl -GET http://localhost:8080/actuator/metrics/hello.counter | jq
{
  "name": "hello.counter",
  "description": null,
  "baseUnit": null,
  "measurements": [
    {
      "statistic": "COUNT",
      "value": 1
    }
  ],
  "availableTags": [
    {
      "tag": "app",
      "values": [
        "demo"
      ]
    }
  ]
}

另外，如果你的指标依赖于另一个 Bean，推荐使用 MeterBinder 来构建指标：

@Configuration
public class DemoListConfiguration {
    
    @Bean
    public List<String> demoList() {
        return new ArrayList<>();
    }

    @Bean
    public MeterBinder demoListSize(List<String> demoList) {
        return (registry) -> Gauge.builder("list.size", demoList::size).register(registry);
    }
}

Mappings (mappings)

/mappings 端点用来返回应用中的所有 URI 路径，以及它们和控制器的映射关系：

$ curl -s http://localhost:8080/actuator/mappings | jq
{
  "contexts": {
    "application": {
      "mappings": {
        "dispatcherServlets": {
          "dispatcherServlet": [
            {
              "handler": "com.example.demo.DemoController#hello()",
              "predicate": "{GET [/hello]}",
              "details": {
                "handlerMethod": {
                  "className": "com.example.demo.DemoController",
                  "name": "hello",
                  "descriptor": "()Ljava/lang/String;"
                },
                "requestMappingConditions": {
                  "consumes": [],
                  "headers": [],
                  "methods": [
                    "GET"
                  ],
                  "params": [],
                  "patterns": [
                    "/hello"
                  ],
                  "produces": []
                }
              }
            },
            ...
          ]
        },
        "servletFilters": [
          {
            "servletNameMappings": [],
            "urlPatternMappings": [
              "/*"
            ],
            "name": "webMvcMetricsFilter",
            "className": "org.springframework.boot.actuate.metrics.web.servlet.WebMvcMetricsFilter"
          },
          {
            "servletNameMappings": [],
            "urlPatternMappings": [
              "/*"
            ],
            "name": "requestContextFilter",
            "className": "org.springframework.boot.web.servlet.filter.OrderedRequestContextFilter"
          },
          ...
        ],
        "servlets": [
          {
            "mappings": [
              "/"
            ],
            "name": "dispatcherServlet",
            "className": "org.springframework.web.servlet.DispatcherServlet"
          }
        ]
      },
      "parentId": null
    }
  }
}

从结果中可以看到应用程序都定义了哪些接口（包含了每个接口的地址，处理器，匹配条件等等），包括 Actuator 接口，列表有点长，这里是完整的结果。

除此之外，还可以看到应用中定义了哪些 servlets，默认就只有一个 dispatcherServlet，以及有哪些 servletFilters，比如 requestContextFilter 和 webMvcMetricsFilter 等。

Shutdown (shutdown)

/shutdown 端点用于关闭程序，默认是不开放的，需要通过下面的配置打开：

management.endpoint.shutdown.enabled=true

开启后就可以向该端点发送 POST 请求来关闭程序了：

$ curl -s -X POST http://localhost:8080/actuator/shutdown
{"message":"Shutting down, bye..."}

自定义端点

有时候我们希望将应用程序的内部状态暴露出来，或对内部状态进行修改，这时我们就可以使用 Actuator 的自定义端点功能，通过 @Endpoint 注解即可以注册一个新端点：

@Endpoint(id = "test")
@Configuration
public class TestEndpoint {
    
    private final List<String> demoList;
    public TestEndpoint(List<String> demoList) {
        this.demoList = demoList;
    }

    @ReadOperation
    public List<String> getDemoList() {
        return this.demoList;
    }
}

可以看到我们在上面的方法上加了一个 @ReadOperation 注解，表示这个端点可以通过 GET 访问：

$ curl -s http://localhost:8080/actuator/test | jq

除此之外，也可以使用 @WriteOperation 或 @DeleteOperation 注解，分别表示 POST 或 DELETE 请求。

使用 Spring Security 对端点进行安全保护

由于 Actuator 端点暴露出来的信息较为敏感，存在一定的安全风险，所以我们必须防止未经授权的外部访问。首先添加 Spring Security 依赖：

<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-security</artifactId>
</dependency>

然后定义一个 SecurityFilterChain bean，对所有的 Actuator 端点开启认证，必须是 ACTUATOR_ADMIN 角色的用户才能访问，认证方式使用简单的 HTTP Basic 认证：

@Configuration
public class DemoSecurityConfiguration {
    
    @Bean
    public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
        http.requestMatcher(EndpointRequest.toAnyEndpoint());
        http.authorizeRequests((requests) -> requests.anyRequest().hasRole("ACTUATOR_ADMIN"));
        http.httpBasic(withDefaults());
        return http.build();
    }
}

在配置文件中添加一个 ACTUATOR_ADMIN 角色的用户：

spring.security.user.name=admin
spring.security.user.password=admin
spring.security.user.roles=ACTUATOR_ADMIN

这样我们在访问 Actuator 端点时，必须输入用户名和密码（admin/admin）。

注意上面的代码中我们使用 http.requestMatcher(EndpointRequest.toAnyEndpoint()) 只对 Actuator 端点开启认证，应用程序的其他接口不受影响。如果要对其他接口开启认证，可以再定义一个 SecurityFilterChain bean 对其他接口进行配置。

通过 JMX 访问 Actuator 端点

Spring Boot Actuator 端点不仅可以通过 HTTP 接口访问，而且还可以通过 JMX 访问，我们运行 jconsole 连接我们的应用程序：

在选项卡中选择 MBean，左侧会以树形显示应用程序中的所有 MBean，我们找到 org.springframework.boot 就可以看到暴露的 Endpoint 列表了：

随便选择一个 Endpoint，再打开操作界面，然后就可以像调用方法一样访问端点了。

参考

1. Production-ready Features
2. Spring Boot Actuator Web API Documentation
3. Spring Boot Actuator 模块 详解：健康检查，度量，指标收集和监控
4. Spring Boot (十九)：使用 Spring Boot Actuator 监控应用
5. Spring Boot Actuator
6. Building a RESTful Web Service with Spring Boot Actuator

更多

其他端点

除了 Actuator 的原生端点，还有一些特殊的端点，需要在特定的条件下才会有。

在我们的日常工作中，经常需要从头开始创建一个 Spring 项目，很多人的做法是，复制一份已有的项目，然后改目录名，改项目名，改包名，然后再把一些不要的文件删掉，只保留项目的基本框架。

实际上，这样操作后保留下来的基本框架代码就是 脚手架 代码，有很多的工具可以帮我们自动生成脚手架代码。

Maven Archetype

说起项目脚手架，我们最先想到的肯定是 Maven Archetype，在命令行中输入 mvn archetype:generate 进入交互模式，默认情况下会列出所有的 Archetype，这个清单可能非常长，让你不知道选哪个，可以通过 -Dfilter 参数进行过滤：

> mvn archetype:generate -Dfilter=org.apache.maven:
[INFO] Scanning for projects...
[INFO]
[INFO] ------------------< org.apache.maven:standalone-pom >-------------------
[INFO] Building Maven Stub Project (No POM) 1
[INFO] --------------------------------[ pom ]---------------------------------
[INFO]
[INFO] >>> maven-archetype-plugin:3.2.1:generate (default-cli) > generate-sources @ standalone-pom >>>
[INFO]
[INFO] <<< maven-archetype-plugin:3.2.1:generate (default-cli) < generate-sources @ standalone-pom <<<
[INFO]
[INFO]
[INFO] --- maven-archetype-plugin:3.2.1:generate (default-cli) @ standalone-pom ---
[INFO] Generating project in Interactive mode
[INFO] No archetype defined. Using maven-archetype-quickstart (org.apache.maven.archetypes:maven-archetype-quickstart:1.0)
Choose archetype:
1: remote -> org.apache.maven.archetypes:maven-archetype-archetype (An archetype which contains a sample archetype.)
2: remote -> org.apache.maven.archetypes:maven-archetype-j2ee-simple (An archetype which contains a simplified sample J2EE application.)
3: remote -> org.apache.maven.archetypes:maven-archetype-marmalade-mojo (-)
4: remote -> org.apache.maven.archetypes:maven-archetype-mojo (An archetype which contains a sample a sample Maven plugin.)
5: remote -> org.apache.maven.archetypes:maven-archetype-plugin (An archetype which contains a sample Maven plugin.)
6: remote -> org.apache.maven.archetypes:maven-archetype-plugin-site (An archetype which contains a sample Maven plugin site. This archetype can be layered upon an
    existing Maven plugin project.)
7: remote -> org.apache.maven.archetypes:maven-archetype-portlet (An archetype which contains a sample JSR-268 Portlet.)
8: remote -> org.apache.maven.archetypes:maven-archetype-profiles (-)
9: remote -> org.apache.maven.archetypes:maven-archetype-quickstart (An archetype which contains a sample Maven project.)
10: remote -> org.apache.maven.archetypes:maven-archetype-simple (An archetype which contains a simple Maven project.)
11: remote -> org.apache.maven.archetypes:maven-archetype-site (An archetype which contains a sample Maven site which demonstrates some of the supported document types like
    APT, XDoc, and FML and demonstrates how to i18n your site. This archetype can be layered
    upon an existing Maven project.)
12: remote -> org.apache.maven.archetypes:maven-archetype-site-simple (An archetype which contains a sample Maven site.)
13: remote -> org.apache.maven.archetypes:maven-archetype-site-skin (An archetype which contains a sample Maven Site Skin.)
14: remote -> org.apache.maven.archetypes:maven-archetype-webapp (An archetype which contains a sample Maven Webapp project.)
Choose a number or apply filter (format: [groupId:]artifactId, case sensitive contains): 9:

我们这边使用 -Dfilter=org.apache.maven: 过滤条件列出了 Maven 官方的 14 个 Archetype，系统默认会选中 maven-archetype-quickstart，这是官方推荐的 Maven 项目脚手架，然后我们需要选择版本号，并填写项目的 groupId、artifactId、version 和 package：

Choose org.apache.maven.archetypes:maven-archetype-quickstart version:
1: 1.0-alpha-1
2: 1.0-alpha-2
3: 1.0-alpha-3
4: 1.0-alpha-4
5: 1.0
6: 1.1
7: 1.3
8: 1.4
Choose a number: 8:

Define value for property 'groupId': com.example
Define value for property 'artifactId': demo
Define value for property 'version' 1.0-SNAPSHOT: :
Define value for property 'package' com.example: :
Confirm properties configuration:
groupId: com.example
artifactId: demo
version: 1.0-SNAPSHOT
package: com.example
 Y: : Y
[INFO] ----------------------------------------------------------------------------
[INFO] Using following parameters for creating project from Archetype: maven-archetype-quickstart:1.4
[INFO] ----------------------------------------------------------------------------
[INFO] Parameter: groupId, Value: com.example
[INFO] Parameter: artifactId, Value: demo
[INFO] Parameter: version, Value: 1.0-SNAPSHOT
[INFO] Parameter: package, Value: com.example
[INFO] Parameter: packageInPathFormat, Value: com/example
[INFO] Parameter: package, Value: com.example
[INFO] Parameter: groupId, Value: com.example
[INFO] Parameter: artifactId, Value: demo
[INFO] Parameter: version, Value: 1.0-SNAPSHOT
[INFO] Project created from Archetype in dir: C:\Users\aneasystone\Desktop\demo
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  04:07 min
[INFO] Finished at: 2022-03-17T07:04:14+08:00
[INFO] ------------------------------------------------------------------------

这样，一个简单的 Maven 项目就生成了，生成的项目结构如下：

$ tree demo
demo
├── pom.xml
└── src
    ├── main
    │   └── java
    │       └── com
    │           └── example
    │               └── App.java
    └── test
        └── java
            └── com
                └── example
                    └── AppTest.java

当然，这个示例代码还是太简单了，我们希望能能自动生成一个 Spring Boot 项目的代码框架，好在 Spring 官方也提供了很多种不同的 Maven Archetype，通过 -Dfilter=org.springframework: 参数过滤下看看：

Choose archetype:
1: remote -> org.springframework.boot:spring-boot-sample-actuator-archetype (Spring Boot Actuator Sample)
2: remote -> org.springframework.boot:spring-boot-sample-actuator-log4j-archetype (Spring Boot Actuator Log4J Sample)
3: remote -> org.springframework.boot:spring-boot-sample-actuator-noweb-archetype (Spring Boot Actuator Non-Web Sample)
4: remote -> org.springframework.boot:spring-boot-sample-actuator-ui-archetype (Spring Boot Actuator UI Sample)
5: remote -> org.springframework.boot:spring-boot-sample-amqp-archetype (Spring Boot AMQP Sample)
6: remote -> org.springframework.boot:spring-boot-sample-aop-archetype (Spring Boot AOP Sample)
7: remote -> org.springframework.boot:spring-boot-sample-batch-archetype (Spring Boot Batch Sample)
8: remote -> org.springframework.boot:spring-boot-sample-data-jpa-archetype (Spring Boot Data JPA Sample)
9: remote -> org.springframework.boot:spring-boot-sample-data-mongodb-archetype (Spring Boot Data MongoDB Sample)
10: remote -> org.springframework.boot:spring-boot-sample-data-redis-archetype (Spring Boot Data Redis Sample)
11: remote -> org.springframework.boot:spring-boot-sample-data-rest-archetype (Spring Boot Data REST Sample)
12: remote -> org.springframework.boot:spring-boot-sample-integration-archetype (Spring Boot Integration Sample)
13: remote -> org.springframework.boot:spring-boot-sample-jetty-archetype (Spring Boot Jetty Sample)
14: remote -> org.springframework.boot:spring-boot-sample-profile-archetype (Spring Boot Profile Sample)
15: remote -> org.springframework.boot:spring-boot-sample-secure-archetype (Spring Boot Security Sample)
16: remote -> org.springframework.boot:spring-boot-sample-servlet-archetype (Spring Boot Servlet Sample)
17: remote -> org.springframework.boot:spring-boot-sample-simple-archetype (Spring Boot Simple Sample)
18: remote -> org.springframework.boot:spring-boot-sample-tomcat-archetype (Spring Boot Tomcat Sample)
19: remote -> org.springframework.boot:spring-boot-sample-traditional-archetype (Spring Boot Traditional Sample)
20: remote -> org.springframework.boot:spring-boot-sample-web-jsp-archetype (Spring Boot Web JSP Sample)
21: remote -> org.springframework.boot:spring-boot-sample-web-method-security-archetype (Spring Boot Web Method Security Sample)
22: remote -> org.springframework.boot:spring-boot-sample-web-secure-archetype (Spring Boot Web Secure Sample)
23: remote -> org.springframework.boot:spring-boot-sample-web-static-archetype (Spring Boot Web Static Sample)
24: remote -> org.springframework.boot:spring-boot-sample-web-ui-archetype (Spring Boot Web UI Sample)
25: remote -> org.springframework.boot:spring-boot-sample-websocket-archetype (Spring Boot WebSocket Sample)
26: remote -> org.springframework.boot:spring-boot-sample-xml-archetype (Spring Boot XML Sample)
27: remote -> org.springframework.osgi:spring-osgi-bundle-archetype (Spring OSGi Maven2 Archetype)
28: remote -> org.springframework.ws:spring-ws-archetype (Spring Web Services Maven2 Archetype.)

我们选择 spring-boot-sample-simple-archetype 就可以生成一个简单的 Spring Boot 项目，生成的项目结构如下：

$ tree demo
demo
├── build.gradle
├── pom.xml
└── src
    ├── main
    │   ├── java
    │   │   └── com
    │   │       └── example
    │   │           └── simple
    │   │               ├── SampleSimpleApplication.java
    │   │               └── service
    │   │                   └── HelloWorldService.java
    │   └── resources
    │       └── application.properties
    └── test
        ├── java
        │   └── com
        │       └── example
        │           └── simple
        │               ├── SampleSimpleApplicationTests.java
        │               └── SpringTestSampleSimpleApplicationTests.java
        └── resources
            └── application.properties

我们也可以不用交互模式，直接一行命令生成：

$ mvn archetype:generate \
     -DarchetypeGroupId=org.springframework.boot \
     -DarchetypeArtifactId=spring-boot-sample-simple-archetype \
     -DarchetypeVersion=1.0.2.RELEASE \
     -DgroupId=com.example \
     -DartifactId=demo \
     -Dversion=1.0.0-SNAPSHOT \
     -DinteractiveMode=false

除了官方的 Maven Archetype，网上还有很多人自己写的 Archetype，集成了一些常用的框架和工具，也值得尝试：

• https://github.com/Romeh/spring-boot-quickstart-archtype
• https://github.com/netyjq/spring-boot-archetype
• https://github.com/drtrang/maven-archetype-springboot

Spring Initializr

虽然使用 Maven Archetype 创建 Spring 项目非常简单，但是通过 Maven Archetype 生成的代码比较死板，如果想在生成的时候动态添加一些依赖，就需要手工去修改 pom.xml 文件了。Spring 官方提供了另一种创建项目的方式：Spring Initializr，下图是使用 Spring Initializr 生成项目脚手架代码的一个示例：

在这个页面中，我们需要填写这些信息：

• 项目类型

  • Maven
  • Gradle

• 语言类型

  • Java
  • Kotlin
  • Groovy
• Spring Boot 版本

• 项目基本信息

  • Group
  • Artifact
  • Name
  • Description
  • Package name
  • Packaging
  • Java
• 项目依赖

这里我选择的是 Maven 项目，语言类型为 Java，Spring Boot 版本为 2.6.4，项目基本信息为默认的 demo，打包方式为 jar，并添加了一个 Spring Web 依赖。生成的项目代码结构如下：

demo
├── HELP.md
├── mvnw
├── mvnw.cmd
├── pom.xml
└── src
    ├── main
    │   ├── java
    │   │   └── com
    │   │       └── example
    │   │           └── demo
    │   │               └── DemoApplication.java
    │   └── resources
    │       ├── application.properties
    │       ├── static
    │       └── templates
    └── test
        └── java
            └── com
                └── example
                    └── demo
                        └── DemoApplicationTests.java

按照 Spring Boot 快速入门教程，我们在 DemoApplication.java 里加几行代码：

package com.example.demo;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

@SpringBootApplication
@RestController
public class DemoApplication {

    public static void main(String[] args) {
        SpringApplication.run(DemoApplication.class, args);
    }

    @GetMapping("/hello")
    public String hello(@RequestParam(value = "name", defaultValue = "World") String name) {
        return String.format("Hello %s!", name);
    }
}

至此一个简单的 Web 项目就完成了，然后执行 ./mvnw spring-boot:run 命令，第一次执行可能比较慢，这是在下载程序所需要的依赖，等启动结束后打开浏览器，访问 http://localhost:8080/hello 页面，就可以看到我们熟悉的 Hello World 了。

Spring Tool Suite

Spring Tool Suite 被简称为 STS，是 Spring 官方推出的一套用于方便开发 Spring 项目的工具集，它可以集成到几乎所有的 IDE 中，比如：Eclipse、VS Code 或 Theia IDE 等。

这里以 VS Code 为例，体验下使用 STS 快速创建 Spring 项目脚手架代码。首先在 VS Code 的插件市场搜索 Spring Boot Extension Pack：

可以看到 STS 是一套工具集，包含了：

• Spring Boot Tools
• Spring Boot Dashboard
• Spring Initializr Java Support

如果我们只想体验 Spring Initializr 的功能，也可以只安装 Spring Initializr Java Support 这个插件即可。安装完成后，通过 Ctrl + Shift + P 打开命令面板，输入 Spring Initializr 按提示就可以快速创建一个 Spring 项目，放一张官方的动图：

Spring Boot CLI

Spring Boot CLI 的安装非常方便，我们可以直接从 Spring 仓库中下载 spring-boot-cli-2.6.4-bin.zip，将其解压到某个目录中，然后将 bin 目录添加到 PATH 环境变量。

使用 spring --version 验证 Spring Boot CLI 是否安装成功：

> spring --version
Spring CLI v2.6.4

Spring Boot CLI 可以用来执行 Groovy 脚本，也可以用来初始化新的 Spring 项目。下面是一个执行 Groovy 脚本的例子，首先创建一个文件 hello.groovy：

@RestController
class ThisWillActuallyRun {
    @RequestMapping("/")
    String home() {
        "Hello World!"
    }
}

然后执行命令：

> spring run hello.groovy

这样，一个简单的 Web 项目就启动好了，Spring Boot CLI 会自动解析 Groovy 脚本中的依赖并运行，打开浏览器访问 http://localhost:8080 就看见我们熟悉的 Hello World 了。

下面是通过 Spring Boot CLI 初始化项目的例子：

> spring init --name demo \
    --artifact-id demo \
    --group-id com.example \
    --language java \
    --java-version 11 \
    --boot-version 2.6.4 \
    --type maven-project \
    --dependencies web \
    demo

这个命令和从 start.spring.io 上生成项目是完全一样的。可以通过 spring help init 了解各个参数的含义，每个参数都有默认值，所以你也可以直接使用 spring init demo 生成一个默认的示例项目。

参考

1. Introduction to Archetypes
2. Spring Quickstart Guide
3. Spring Initializr Reference Guide
4. Spring Boot Reference Documentation

更多

1. 创建自己的 Maven Archetype

• Guide to Creating Archetypes
• Multi-Module Maven Archetypes

2. Spring Initializr 支持的依赖一览

在 Spring Initializr 上创建项目时，可以手工添加项目依赖，支持的依赖列表如下（记住这些依赖，大多是 Spring 生态中必学必会的技术）：

Developer Tools

• Spring Native

  • Incubating support for compiling Spring applications to native executables using the GraalVM native-image compiler.

• Spring Boot DevTools

  • Provides fast application restarts, LiveReload, and configurations for enhanced development experience.

• Lombok

  • Java annotation library which helps to reduce boilerplate code.

• Spring Configuration Processor

  • Generate metadata for developers to offer contextual help and "code completion" when working with custom configuration keys (ex.application.properties/.yml files).

Web

• Spring Web

  • Build web, including RESTful, applications using Spring MVC. Uses Apache Tomcat as the default embedded container.

• Spring Reactive Web

  • Build reactive web applications with Spring WebFlux and Netty.

• Spring GraphQL

  • Build GraphQL applications with Spring GraphQL and GraphQL Java.

• Rest Repositories

  • Exposing Spring Data repositories over REST via Spring Data REST.

• Spring Session

  • Provides an API and implementations for managing user session information.

• Rest Repositories HAL Explorer

  • Browsing Spring Data REST repositories in your browser.

• Spring HATEOAS

  • Eases the creation of RESTful APIs that follow the HATEOAS principle when working with Spring / Spring MVC.

• Spring Web Services

  • Facilitates contract-first SOAP development. Allows for the creation of flexible web services using one of the many ways to manipulate XML payloads.

• Jersey

  • Framework for developing RESTful Web Services in Java that provides support for JAX-RS APIs.

• Vaadin

  • A web framework that allows you to write UI in pure Java without getting bogged down in JS, HTML, and CSS.

Template Engines

• Thymeleaf

  • A modern server-side Java template engine for both web and standalone environments. Allows HTML to be correctly displayed in browsers and as static prototypes.

• Apache Freemarker

  • Java library to generate text output (HTML web pages, e-mails, configuration files, source code, etc.) based on templates and changing data.

• Mustache

  • Logic-less Templates. There are no if statements, else clauses, or for loops. Instead there are only tags.

• Groovy Templates

  • Groovy templating engine.

Security

• Spring Security

  • Highly customizable authentication and access-control framework for Spring applications.

• OAuth2 Client

  • Spring Boot integration for Spring Security's OAuth2/OpenID Connect client features.

• OAuth2 Resource Server

  • Spring Boot integration for Spring Security's OAuth2 resource server features.

• Spring LDAP

  • Makes it easier to build Spring based applications that use the Lightweight Directory Access Protocol.

• Okta

  • Okta specific configuration for Spring Security/Spring Boot OAuth2 features. Enable your Spring Boot application to work with Okta via OAuth 2.0/OIDC.

SQL

• JDBC API

  • Database Connectivity API that defines how a client may connect and query a database.

• Spring Data JPA

  • Persist data in SQL stores with Java Persistence API using Spring Data and Hibernate.

• Spring Data JDBC

  • Persist data in SQL stores with plain JDBC using Spring Data.

• Spring Data R2DBC

  • Provides Reactive Relational Database Connectivity to persist data in SQL stores using Spring Data in reactive applications.

• MyBatis Framework

  • Persistence framework with support for custom SQL, stored procedures and advanced mappings. MyBatis couples objects with stored procedures or SQL statements using a XML descriptor or annotations.

• Liquibase Migration

  • Liquibase database migration and source control library.

• Flyway Migration

  • Version control for your database so you can migrate from any version (incl. an empty database) to the latest version of the schema.

• JOOQ Access Layer

  • Generate Java code from your database and build type safe SQL queries through a fluent API.

• IBM DB2 Driver

  • A JDBC driver that provides access to IBM DB2.

• Apache Derby Database

  • An open source relational database implemented entirely in Java.

• H2 Database

  • Provides a fast in-memory database that supports JDBC API and R2DBC access, with a small (2mb) footprint. Supports embedded and server modes as well as a browser based console application.

• HyperSQL Database

  • Lightweight 100% Java SQL Database Engine.

• MariaDB Driver

  • MariaDB JDBC and R2DBC driver.

• MS SQL Server Driver

  • A JDBC and R2DBC driver that provides access to Microsoft SQL Server and Azure SQL Database from any Java application.

• MySQL Driver

  • MySQL JDBC and R2DBC driver.

• Oracle Driver

  • A JDBC driver that provides access to Oracle.

• PostgreSQL Driver

  • A JDBC and R2DBC driver that allows Java programs to connect to a PostgreSQL database using standard, database independent Java code.

NoSQL

• Spring Data Redis (Access+Driver)

  • Advanced and thread-safe Java Redis client for synchronous, asynchronous, and reactive usage. Supports Cluster, Sentinel, Pipelining, Auto-Reconnect, Codecs and much more.

• Spring Data Reactive Redis

  • Access Redis key-value data stores in a reactive fashion with Spring Data Redis.

• Spring Data MongoDB

  • Store data in flexible, JSON-like documents, meaning fields can vary from document to document and data structure can be changed over time.

• Spring Data Reactive MongoDB

  • Provides asynchronous stream processing with non-blocking back pressure for MongoDB.

• Spring Data Elasticsearch (Access+Driver)

  • A distributed, RESTful search and analytics engine with Spring Data Elasticsearch.

• Spring Data for Apache Cassandra

  • A free and open-source, distributed, NoSQL database management system that offers high-scalability and high-performance.

• Spring Data Reactive for Apache Cassandra

  • Access Cassandra NoSQL Database in a reactive fashion.

• Spring for Apache Geode

  • Apache Geode is a data management platform that helps users build real-time, highly concurrent, highly performant and reliable Spring Boot applications at scale that is compatible with Pivotal Cloud Cache.

• Spring Data Couchbase

  • NoSQL document-oriented database that offers in memory-first architecture, geo-distributed deployments, and workload isolation.

• Spring Data Reactive Couchbase

  • Access Couchbase NoSQL database in a reactive fashion with Spring Data Couchbase.

• Spring Data Neo4j

  • An open source NoSQL database that stores data structured as graphs consisting of nodes, connected by relationships.

Messaging

• Spring Integration

  • Adds support for Enterprise Integration Patterns. Enables lightweight messaging and supports integration with external systems via declarative adapters.

• Spring for RabbitMQ

  • Gives your applications a common platform to send and receive messages, and your messages a safe place to live until received.

• Spring for Apache Kafka

  • Publish, subscribe, store, and process streams of records.

• Spring for Apache Kafka Streams

  • Building stream processing applications with Apache Kafka Streams.

• Spring for Apache ActiveMQ 5

  • Spring JMS support with Apache ActiveMQ 'Classic'.

• Spring for Apache ActiveMQ Artemis

  • Spring JMS support with Apache ActiveMQ Artemis.

• WebSocket

  • Build WebSocket applications with SockJS and STOMP.

• RSocket

  • RSocket.io applications with Spring Messaging and Netty.

• Apache Camel

  • Apache Camel is an open source integration framework that empowers you to quickly and easily integrate various systems consuming or producing data.

• Solace PubSub+

  • Connect to a Solace PubSub+ Advanced Event Broker to publish, subscribe, request/reply and store/replay messages

I/O

• Spring Batch

  • Batch applications with transactions, retry/skip and chunk based processing.

• Validation

  • Bean Validation with Hibernate validator.

• Java Mail Sender

  • Send email using Java Mail and Spring Framework's JavaMailSender.

• Quartz Scheduler

  • Schedule jobs using Quartz.

• Spring cache abstraction

  • Provides cache-related operations, such as the ability to update the content of the cache, but does not provide the actual data store.

• Picocli

  • Build command line applications with picocli.

Ops

• Spring Boot Actuator

  • Supports built in (or custom) endpoints that let you monitor and manage your application - such as application health, metrics, sessions, etc.

• Codecentric's Spring Boot Admin (Client)

  • Required for your application to register with a Codecentric's Spring Boot Admin Server instance.

• Codecentric's Spring Boot Admin (Server)

  • A community project to manage and monitor your Spring Boot applications. Provides a UI on top of the Spring Boot Actuator endpoints.

Observability

• Datadog

  • Publish Micrometer metrics to Datadog, a dimensional time-series SaaS with built-in dashboarding and alerting.

• Influx

  • Publish Micrometer metrics to InfluxDB, a dimensional time-series server that support real-time stream processing of data.

• Graphite

  • Publish Micrometer metrics to Graphite, a hierarchical metrics system backed by a fixed-size database.

• New Relic

  • Publish Micrometer metrics to New Relic, a SaaS offering with a full UI and a query language called NRQL.

• Prometheus

  • Expose Micrometer metrics in Prometheus format, an in-memory dimensional time series database with a simple built-in UI, a custom query language, and math operations.

• Sleuth

  • Distributed tracing via logs with Spring Cloud Sleuth.

• Wavefront

  • Publish Micrometer metrics to Tanzu Observability by Wavefront, a SaaS-based metrics monitoring and analytics platform that lets you visualize, query, and alert over data from across your entire stack.

• Zipkin Client

  • Distributed tracing with an existing Zipkin installation and Spring Cloud Sleuth Zipkin.

Testing

• Spring REST Docs

  • Document RESTful services by combining hand-written with Asciidoctor and auto-generated snippets produced with Spring MVC Test.

• Testcontainers

  • Provide lightweight, throwaway instances of common databases, Selenium web browsers, or anything else that can run in a Docker container.

• Contract Verifier

  • Moves TDD to the level of software architecture by enabling Consumer Driven Contract (CDC) development.

• Contract Stub Runner

  • Stub Runner for HTTP/Messaging based communication. Allows creating WireMock stubs from RestDocs tests.

• Embedded LDAP Server

  • Provides a platform neutral way for running a LDAP server in unit tests.

• Embedded MongoDB Database

  • Provides a platform neutral way for running MongoDB in unit tests.

Spring Cloud

• Cloud Bootstrap

  • Non-specific Spring Cloud features, unrelated to external libraries or integrations (e.g. Bootstrap context and @RefreshScope).

• Function

  • Promotes the implementation of business logic via functions and supports a uniform programming model across serverless providers, as well as the ability to run standalone (locally or in a PaaS).

• Task

  • Allows a user to develop and run short lived microservices using Spring Cloud. Run them locally, in the cloud, and on Spring Cloud Data Flow.

Spring Cloud Tools

• Open Service Broker

  • Framework for building Spring Boot apps that implement the Open Service Broker API, which can deliver services to applications running within cloud native platforms such as Cloud Foundry, Kubernetes and OpenShift.

Spring Cloud Config

• Config Client

  • Client that connects to a Spring Cloud Config Server to fetch the application's configuration.

• Config Server

  • Central management for configuration via Git, SVN, or HashiCorp Vault.

• Vault Configuration

  • Provides client-side support for externalized configuration in a distributed system. Using HashiCorp's Vault you have a central place to manage external secret properties for applications across all environments.

• Apache Zookeeper Configuration

  • Enable and configure common patterns inside your application and build large distributed systems with Apache Zookeeper based components. The provided patterns include Service Discovery and Configuration.

• Consul Configuration

  • Enable and configure the common patterns inside your application and build large distributed systems with Hashicorp’s Consul. The patterns provided include Service Discovery, Distributed Configuration and Control Bus.

Spring Cloud Discovery

• Eureka Discovery Client

  • A REST based service for locating services for the purpose of load balancing and failover of middle-tier servers.

• Eureka Server

  • spring-cloud-netflix Eureka Server.

• Apache Zookeeper Discovery

  • Service discovery with Apache Zookeeper.

• Cloud Foundry Discovery

  • Service discovery with Cloud Foundry.

• Consul Discovery

  • Service discovery with Hashicorp Consul.

Spring Cloud Routing

• Gateway

  • Provides a simple, yet effective way to route to APIs and provide cross cutting concerns to them such as security, monitoring/metrics, and resiliency.

• OpenFeign

  • Declarative REST Client. OpenFeign creates a dynamic implementation of an interface decorated with JAX-RS or Spring MVC annotations.

• Cloud LoadBalancer

  • Client-side load-balancing with Spring Cloud LoadBalancer.

Spring Cloud Circuit Breaker

• Resilience4J

  • Spring Cloud Circuit breaker with Resilience4j as the underlying implementation.

Spring Cloud Messaging

• Cloud Bus

  • Links nodes of a distributed system with a lightweight message broker which can used to broadcast state changes or other management instructions (requires a binder, e.g. Apache Kafka or RabbitMQ).

• Cloud Stream

  • Framework for building highly scalable event-driven microservices connected with shared messaging systems (requires a binder, e.g. Apache Kafka, RabbitMQ or Solace PubSub+).

VMware Tanzu Application Service

• Config Client (TAS)

  • Config client on VMware Tanzu Application Service.

• Service Registry (TAS)

  • Eureka service discovery client on VMware Tanzu Application Service.

Microsoft Azure

• Azure Support

  • Auto-configuration for Azure Services (Service Bus, Storage, Active Directory, Key Vault, and more).

• Azure Active Directory

  • Spring Security integration with Azure Active Directory for authentication.

• Azure Cosmos DB

  • Fully managed NoSQL database service for modern app development, including Spring Data support.

• Azure Key Vault

  • Manage application secrets.

• Azure Storage

  • Azure Storage service integration.

Google Cloud Platform

• GCP Support

  • Contains auto-configuration support for every Spring Cloud GCP integration. Most of the auto-configuration code is only enabled if other dependencies are added to the classpath.

• GCP Messaging

  • Adds the GCP Support entry and all the required dependencies so that the Google Cloud Pub/Sub integration work out of the box.

• GCP Storage

  • Adds the GCP Support entry and all the required dependencies so that the Google Cloud Storage integration work out of the box.

3. 实现自己的 Spring Initializr

Spring Initializr 是一个完全开源的项目，我们可以通过它实现自己的代码脚手架。上面所介绍的 start.spring.io、STS 和 Spring Boot CLI 其实都是通过 Spring Initializr 来实现的，源码如下：

# git clone https://github.com/spring-io/initializr

# git clone https://github.com/spring-io/start.spring.io

另外，阿里的知行动手实验室也基于 Spring Initializr 做了一个类似于 start.spring.io 的脚手架生成站点 start.aliyun.com，在依赖列表中新增了阿里的一些开源项目，而且还提供了常见的几种应用架构的代码示例，有兴趣的同学可以体验下。

4. mvnw 设置代理

直接使用 mvn 命令构建项目时，可以通过 Maven 的配置文件 ~/.m2/settings.xml 来配置代理服务器，如下：

  <proxies>
    <proxy>
      <id>optional</id>
      <active>true</active>
      <protocol>http</protocol>
      <host>localhost</host>
      <port>10809</port>
    </proxy>
  </proxies>

但是使用 mvnw 时，它会自动下载 Maven 并执行而不会使用 settings.xml 中的 Maven 配置。这时我们可以通过 MAVEN_OPTS 环境变量来设置代理：

export MAVEN_OPTS="-Dhttp.proxyHost=127.0.0.1 -Dhttp.proxyPort=10809 -Dhttps.proxyHost=127.0.0.1 -Dhttps.proxyPort=10809"

或者在 .mvn 目录下新建一个 jvm.config 文件：

-Dhttp.proxyHost=127.0.0.1
-Dhttp.proxyPort=10809
-Dhttps.proxyHost=127.0.0.1
-Dhttps.proxyPort=10809

话说在 Spring Cloud Gateway 问世之前，Spring Cloud 的微服务世界里，网关一定非 Netflix Zuul 莫属。但是由于 Zuul 1.x 存在的一些问题，比如阻塞式的 API，不支持 WebSocket 等，一直被人所诟病，而且 Zuul 升级新版本依赖于 Netflix 公司，经过几次跳票之后，Spring 开源社区决定推出自己的网关组件，替代 Netflix Zuul。

从 18 年 6 月 Spring Cloud 发布的 Finchley 版本开始，Spring Cloud Gateway 逐渐崭露头角，它基于 Spring 5.0、Spring Boot 2.0 和 Project Reactor 等技术开发，不仅支持响应式和无阻塞式的 API，而且支持 WebSocket，和 Spring 框架紧密集成。尽管 Zuul 后来也推出了 2.x 版本，在底层使用了异步无阻塞式的 API，大大改善了其性能，但是目前看来 Spring 并没有打算继续集成它的计划。

根据官网的描述，Spring Cloud Gateway 的主要特性如下：

• Built on Spring Framework 5, Project Reactor and Spring Boot 2.0
• Able to match routes on any request attribute
• Predicates and filters are specific to routes
• Hystrix Circuit Breaker integration
• Spring Cloud DiscoveryClient integration
• Easy to write Predicates and Filters
• Request Rate Limiting
• Path Rewriting

可以看出 Spring Cloud Gateway 可以很方便的和 Spring Cloud 生态中的其他组件进行集成（比如：断路器和服务发现），而且提供了一套简单易写的 断言（Predicates，有的地方也翻译成 谓词）和 过滤器（Filters）机制，可以对每个 路由（Routes）进行特殊请求处理。

最近在项目中使用了 Spring Cloud Gateway，并在它的基础上实现了一些高级特性，如限流和留痕，在网关的使用过程中遇到了不少的挑战，于是趁着项目结束，抽点时间系统地学习并总结下。这篇文章主要学习限流技术，首先我会介绍一些常见的限流场景和限流算法，然后介绍一些关于限流的开源项目，学习别人是如何实现限流的，最后介绍我是如何在网关中实现限流的，并分享一些实现过程中的经验和遇到的坑。

一、常见的限流场景

缓存、降级 和 限流 被称为高并发、分布式系统的三驾马车，网关作为整个分布式系统中的第一道关卡，限流功能自然必不可少。通过限流，可以控制服务请求的速率，从而提高系统应对突发大流量的能力，让系统更具弹性。限流有着很多实际的应用场景，比如双十一的秒杀活动， 12306 的抢票等。

1.1 限流的对象

通过上面的介绍，我们对限流的概念可能感觉还是比较模糊，到底限流限的是什么？顾名思义，限流就是限制流量，但这里的流量是一个比较笼统的概念。如果考虑各种不同的场景，限流是非常复杂的，而且和具体的业务规则密切相关，可以考虑如下几种常见的场景：

• 限制某个接口一分钟内最多请求 100 次
• 限制某个用户的下载速度最多 100KB/S
• 限制某个用户同时只能对某个接口发起 5 路请求
• 限制某个 IP 来源禁止访问任何请求

从上面的例子可以看出，根据不同的请求者和请求资源，可以组合出不同的限流规则。可以根据请求者的 IP 来进行限流，或者根据请求对应的用户来限流，又或者根据某个特定的请求参数来限流。而限流的对象可以是请求的频率，传输的速率，或者并发量等，其中最常见的两个限流对象是请求频率和并发量，他们对应的限流被称为 请求频率限流（Request rate limiting）和 并发量限流（Concurrent requests limiting）。传输速率限流 在下载场景下比较常用，比如一些资源下载站会限制普通用户的下载速度，只有购买会员才能提速，这种限流的做法实际上和请求频率限流类似，只不过一个限制的是请求量的多少，一个限制的是请求数据报文的大小。这篇文章主要介绍请求频率限流和并发量限流。

1.2 限流的处理方式

在系统中设计限流方案时，有一个问题值得设计者去仔细考虑，当请求者被限流规则拦截之后，我们该如何返回结果。一般我们有下面三种限流的处理方式：

• 拒绝服务
• 排队等待
• 服务降级

最简单的做法是拒绝服务，直接抛出异常，返回错误信息（比如返回 HTTP 状态码 429 Too Many Requests），或者给前端返回 302 重定向到一个错误页面，提示用户资源没有了或稍后再试。但是对于一些比较重要的接口不能直接拒绝，比如秒杀、下单等接口，我们既不希望用户请求太快，也不希望请求失败，这种情况一般会将请求放到一个消息队列中排队等待，消息队列可以起到削峰和限流的作用。第三种处理方式是服务降级，当触发限流条件时，直接返回兜底数据，比如查询商品库存的接口，可以默认返回有货。

1.3 限流的架构

针对不同的系统架构，需要使用不同的限流方案。如下图所示，服务部署的方式一般可以分为单机模式和集群模式：

单机模式的限流非常简单，可以直接基于内存就可以实现，而集群模式的限流必须依赖于某个“中心化”的组件，比如网关或 Redis，从而引出两种不同的限流架构：网关层限流 和 中间件限流。

网关作为整个分布式系统的入口，承担了所有的用户请求，所以在网关中进行限流是最合适不过的。网关层限流有时也被称为 接入层限流。除了我们使用的 Spring Cloud Gateway，最常用的网关层组件还有 Nginx，可以通过它的 ngx_http_limit_req_module 模块，使用 limit_conn_zone、limit_req_zone、limit_rate 等指令很容易的实现并发量限流、请求频率限流和传输速率限流。这里不对 Nginx 作过多的说明，关于这几个指令的详细信息可以 参考 Nginx 的官方文档。

另一种限流架构是中间件限流，可以将限流的逻辑下沉到服务层。但是集群中的每个服务必须将自己的流量信息统一汇总到某个地方供其他服务读取，一般来说用 Redis 的比较多，Redis 提供的过期特性和 lua 脚本执行非常适合做限流。除了 Redis 这种中间件，还有很多类似的分布式缓存系统都可以使用，如 Hazelcast、Apache Ignite、Infinispan 等。

我们可以更进一步扩展上面的架构，将网关改为集群模式，虽然这还是网关层限流架构，但是由于网关变成了集群模式，所以网关必须依赖于中间件进行限流，这和上面讨论的中间件限流没有区别。

二、常见的限流算法

通过上面的学习，我们知道限流可以分为请求频率限流和并发量限流，根据系统架构的不同，又可以分为网关层限流和分布式限流。在不同的应用场景下，我们需要采用不同的限流算法。这一节将介绍一些主流的限流算法。

有一点要注意的是，利用池化技术也可以达到限流的目的，比如线程池或连接池，但这不是本文的重点。

2.1 固定窗口算法（Fixed Window）

固定窗口算法是一种最简单的限流算法，它根据限流的条件，将请求时间映射到一个时间窗口，再使用计数器累加访问次数。譬如限流条件为每分钟 5 次，那么就按照分钟为单位映射时间窗口，假设一个请求时间为 11:00:45，时间窗口就是 11:00:00 ~ 11:00:59，在这个时间窗口内设定一个计数器，每来一个请求计数器加一，当这个时间窗口的计数器超过 5 时，就触发限流条件。当请求时间落在下一个时间窗口内时（11:01:00 ~ 11:01:59），上一个窗口的计数器失效，当前的计数器清零，重新开始计数。

计数器算法非常容易实现，在单机场景下可以使用 AtomicLong、LongAdder 或 Semaphore 来实现计数，而在分布式场景下可以通过 Redis 的 INCR 和 EXPIRE 等命令并结合 EVAL 或 lua 脚本来实现，Redis 官网提供了几种简单的实现方式。无论是请求频率限流还是并发量限流都可以使用这个算法。

不过这个算法的缺陷也比较明显，那就是存在严重的临界问题。由于每过一个时间窗口，计数器就会清零，这使得限流效果不够平滑，恶意用户可以利用这个特点绕过我们的限流规则。如下图所示，我们的限流条件本来是每分钟 5 次，但是恶意用户在 11:00:00 ~ 11:00:59 这个时间窗口的后半分钟发起 5 次请求，接下来又在 11:01:00 ~ 11:01:59 这个时间窗口的前半分钟发起 5 次请求，这样我们的系统就在 1 分钟内承受了 10 次请求。（图片来源）

2.2 滑动窗口算法（Rolling Window 或 Sliding Window）

为了解决固定窗口算法的临界问题，可以将时间窗口划分成更小的时间窗口，然后随着时间的滑动删除相应的小窗口，而不是直接滑过一个大窗口，这就是滑动窗口算法。我们为每个小时间窗口都设置一个计数器，大时间窗口的总请求次数就是每个小时间窗口的计数器的和。如下图所示，我们的时间窗口是 5 秒，可以按秒进行划分，将其划分成 5 个小窗口，时间每过一秒，时间窗口就滑过一秒：（图片来源）

每次处理请求时，都需要计算所有小时间窗口的计数器的和，考虑到性能问题，划分的小时间窗口不宜过多，譬如限流条件是每小时 N 个，可以按分钟划分为 60 个窗口，而不是按秒划分成 3600 个。当然如果不考虑性能问题，划分粒度越细，限流效果就越平滑。相反，如果划分粒度越粗，限流效果就越不精确，出现临界问题的可能性也就越大，当划分粒度为 1 时，滑动窗口算法就退化成了固定窗口算法。由于这两种算法都使用了计数器，所以也被称为 计数器算法（Counters）。

进一步思考我们发现，如果划分粒度最粗，也就是只有一个时间窗口时，滑动窗口算法退化成了固定窗口算法；那如果我们把划分粒度调到最细，又会如何呢？那么怎样才能让划分的时间窗口最细呢？时间窗口细到一定地步时，意味着每个时间窗口中只能容纳一个请求，这样我们可以省略计数器，只记录每个请求的时间，然后统计一段时间内的请求数有多少个即可。具体的实现可以参考 这里的 Redis sorted set 技巧 和 这里的 Sliding window log 算法。

2.3 漏桶算法（Leaky Bucket）

除了计数器算法，另一个很自然的限流思路是将所有的请求缓存到一个队列中，然后按某个固定的速度慢慢处理，这其实就是漏桶算法（Leaky Bucket）。漏桶算法假设将请求装到一个桶中，桶的容量为 M，当桶满时，请求被丢弃。在桶的底部有一个洞，桶中的请求像水一样按固定的速度（每秒 r 个）漏出来。我们用下面这个形象的图来表示漏桶算法：（图片来源）

桶的上面是个水龙头，我们的请求从水龙头流到桶中，水龙头流出的水速不定，有时快有时慢，这种忽快忽慢的流量叫做 Bursty flow。如果桶中的水满了，多余的水就会溢出去，相当于请求被丢弃。从桶底部漏出的水速是固定不变的，可以看出漏桶算法可以平滑请求的速率。

漏桶算法可以通过一个队列来实现，如下图所示：

当请求到达时，不直接处理请求，而是将其放入一个队列，然后另一个线程以固定的速率从队列中读取请求并处理，从而达到限流的目的。注意的是这个队列可以有不同的实现方式，比如设置请求的存活时间，或将队列改造成 PriorityQueue，根据请求的优先级排序而不是先进先出。当然队列也有满的时候，如果队列已经满了，那么请求只能被丢弃了。漏桶算法有一个缺陷，在处理突发流量时效率很低，于是人们又想出了下面的令牌桶算法。

2.4 令牌桶算法（Token Bucket）

令牌桶算法（Token Bucket）是目前应用最广泛的一种限流算法，它的基本思想由两部分组成：生成令牌 和 消费令牌。

• 生成令牌：假设有一个装令牌的桶，最多能装 M 个，然后按某个固定的速度（每秒 r 个）往桶中放入令牌，桶满时不再放入；
• 消费令牌：我们的每次请求都需要从桶中拿一个令牌才能放行，当桶中没有令牌时即触发限流，这时可以将请求放入一个缓冲队列中排队等待，或者直接拒绝；

令牌桶算法的图示如下：（图片来源）

在上面的图中，我们将请求放在一个缓冲队列中，可以看出这一部分的逻辑和漏桶算法几乎一模一样，只不过在处理请求上，一个是以固定速率处理，一个是从桶中获取令牌后才处理。

仔细思考就会发现，令牌桶算法有一个很关键的问题，就是桶大小的设置，正是这个参数可以让令牌桶算法具备处理突发流量的能力。譬如将桶大小设置为 100，生成令牌的速度设置为每秒 10 个，那么在系统空闲一段时间的之后（桶中令牌一直没有消费，慢慢的会被装满），突然来了 50 个请求，这时系统可以直接按每秒 50 个的速度处理，随着桶中的令牌很快用完，处理速度又会慢慢降下来，和生成令牌速度趋于一致。这是令牌桶算法和漏桶算法最大的区别，漏桶算法无论来了多少请求，只会一直以每秒 10 个的速度进行处理。当然，处理突发流量虽然提高了系统性能，但也给系统带来了一定的压力，如果桶大小设置不合理，突发的大流量可能会直接压垮系统。

通过上面对令牌桶的原理分析，一般会有两种不同的实现方式。第一种方式是启动一个内部线程，不断的往桶中添加令牌，处理请求时从桶中获取令牌，和上面图中的处理逻辑一样。第二种方式不依赖于内部线程，而是在每次处理请求之前先实时计算出要填充的令牌数并填充，然后再从桶中获取令牌。下面是第二种方式的一种经典实现，其中 capacity 表示令牌桶大小，refillTokensPerOneMillis 表示填充速度，每毫秒填充多少个，availableTokens 表示令牌桶中还剩多少个令牌，lastRefillTimestamp 表示上一次填充时间。

public class TokenBucket {

    private final long capacity;
    private final double refillTokensPerOneMillis;
    private double availableTokens;
    private long lastRefillTimestamp;

    public TokenBucket(long capacity, long refillTokens, long refillPeriodMillis) {
        this.capacity = capacity;
        this.refillTokensPerOneMillis = (double) refillTokens / (double) refillPeriodMillis;
        this.availableTokens = capacity;
        this.lastRefillTimestamp = System.currentTimeMillis();
    }

    synchronized public boolean tryConsume(int numberTokens) {
        refill();
        if (availableTokens < numberTokens) {
            return false;
        } else {
            availableTokens -= numberTokens;
            return true;
        }
    }

    private void refill() {
        long currentTimeMillis = System.currentTimeMillis();
        if (currentTimeMillis > lastRefillTimestamp) {
            long millisSinceLastRefill = currentTimeMillis - lastRefillTimestamp;
            double refill = millisSinceLastRefill * refillTokensPerOneMillis;
            this.availableTokens = Math.min(capacity, availableTokens + refill);
            this.lastRefillTimestamp = currentTimeMillis;
        }
    }
}

可以像下面这样创建一个令牌桶（桶大小为 100，且每秒生成 100 个令牌）：

TokenBucket limiter = new TokenBucket(100, 100, 1000);

从上面的代码片段可以看出，令牌桶算法的实现非常简单也非常高效，仅仅通过几个变量的运算就实现了完整的限流功能。核心逻辑在于 refill() 这个方法，在每次消费令牌时，计算当前时间和上一次填充的时间差，并根据填充速度计算出应该填充多少令牌。在重新填充令牌后，再判断请求的令牌数是否足够，如果不够，返回 false，如果足够，则减去令牌数，并返回 true。

在实际的应用中，往往不会直接使用这种原始的令牌桶算法，一般会在它的基础上作一些改进，比如，填充速率支持动态调整，令牌总数支持透支，基于 Redis 支持分布式限流等，不过总体来说还是符合令牌桶算法的整体框架，我们在后面学习一些开源项目时对此会有更深的体会。

三、一些开源项目

有很多开源项目中都实现了限流的功能，这一节通过一些开源项目的学习，了解限流是如何实现的。

3.1 Guava 的 RateLimiter

Google Guava 是一个强大的核心库，包含了很多有用的工具类，例如：集合、缓存、并发库、字符串处理、I/O 等等。其中在并发库中，Guava 提供了两个和限流相关的类：RateLimiter 和 SmoothRateLimiter。Guava 的 RateLimiter 基于令牌桶算法实现，不过在传统的令牌桶算法基础上做了点改进，支持两种不同的限流方式：平滑突发限流（SmoothBursty） 和 平滑预热限流（SmoothWarmingUp）。

下面的方法可以创建一个平滑突发限流器（SmoothBursty）：

RateLimiter limiter = RateLimiter.create(5); 

RateLimiter.create(5) 表示这个限流器容量为 5，并且每秒生成 5 个令牌，也就是每隔 200 毫秒生成一个。我们可以使用 limiter.acquire() 消费令牌，如果桶中令牌足够，返回 0，如果令牌不足，则阻塞等待，并返回等待的时间。我们连续请求几次：

System.out.println(limiter.acquire());
System.out.println(limiter.acquire());
System.out.println(limiter.acquire());
System.out.println(limiter.acquire());

输出结果如下：

0.0
0.198239
0.196083
0.200609

可以看出限流器创建之后，初始会有一个令牌，然后每隔 200 毫秒生成一个令牌，所以第一次请求直接返回 0，后面的请求都会阻塞大约 200 毫秒。另外，SmoothBursty 还具有应对突发的能力，而且 还允许消费未来的令牌，比如下面的例子：

RateLimiter limiter = RateLimiter.create(5);
System.out.println(limiter.acquire(10));
System.out.println(limiter.acquire(1));
System.out.println(limiter.acquire(1));

会得到类似下面的输出：

0.0
1.997428
0.192273
0.200616

限流器创建之后，初始令牌只有一个，但是我们请求 10 个令牌竟然也通过了，只不过看后面请求发现，第二次请求花了 2 秒左右的时间把前面的透支的令牌给补上了。

Guava 支持的另一种限流方式是平滑预热限流器（SmoothWarmingUp），可以通过下面的方法创建：

RateLimiter limiter = RateLimiter.create(2, 3, TimeUnit.SECONDS);
System.out.println(limiter.acquire(1));
System.out.println(limiter.acquire(1));
System.out.println(limiter.acquire(1));
System.out.println(limiter.acquire(1));
System.out.println(limiter.acquire(1));

第一个参数还是每秒创建的令牌数量，这里是每秒 2 个，也就是每 500 毫秒生成一个，后面的参数表示从冷启动速率过渡到平均速率的时间间隔，也就是所谓的热身时间间隔（warm up period）。我们看下输出结果：

0.0
1.329289
0.994375
0.662888
0.501287

第一个请求还是立即得到令牌，但是后面的请求和上面平滑突发限流就完全不一样了，按理来说 500 毫秒就会生成一个令牌，但是我们发现第二个请求却等了 1.3s，而不是 0.5s，后面第三个和第四个请求也等了一段时间。不过可以看出，等待时间在慢慢的接近 0.5s，直到第五个请求等待时间才开始变得正常。从第一个请求到第五个请求，这中间的时间间隔就是热身阶段，可以算出热身的时间就是我们设置的 3 秒。

关于热身的算法很有意思，也比较烧脑，有兴趣的同学可以参考 这里 和 这里 的过程分析。

3.2 Bucket4j

Bucket4j 是一个基于令牌桶算法实现的强大的限流库，它不仅支持单机限流，还支持通过诸如 Hazelcast、Ignite、Coherence、Infinispan 或其他兼容 JCache API (JSR 107) 规范的分布式缓存实现分布式限流。

在使用 Bucket4j 之前，我们有必要先了解 Bucket4j 中的几个核心概念：

• Bucket
• Bandwidth
• Refill

Bucket 接口代表了令牌桶的具体实现，也是我们操作的入口。它提供了诸如 tryConsume 和 tryConsumeAndReturnRemaining 这样的方法供我们消费令牌。可以通过下面的构造方法来创建 Bucket：

Bucket bucket = Bucket4j.builder().addLimit(limit).build();
if(bucket.tryConsume(1)) {
    System.out.println("ok");
} else {
    System.out.println("error");
}

Bandwidth 的意思是带宽，可以理解为限流的规则。Bucket4j 提供了两种方法来创建 Bandwidth：simple 和 classic。下面是 simple 方式创建的 Bandwidth，表示桶大小为 10，填充速度为每分钟 10 个令牌：

Bandwidth limit = Bandwidth.simple(10, Duration.ofMinutes(1));

simple 方式桶大小和填充速度是一样的，classic 方式更灵活一点，可以自定义填充速度，下面的例子表示桶大小为 10，填充速度为每分钟 5 个令牌：

Refill filler = Refill.greedy(5, Duration.ofMinutes(1));
Bandwidth limit = Bandwidth.classic(10, filler);

其中，Refill 用于填充令牌桶，可以通过它定义填充速度，Bucket4j 有两种填充令牌的策略：间隔策略（intervally） 和 贪婪策略（greedy）。在上面的例子中我们使用的是贪婪策略，如果使用间隔策略可以像下面这样创建 Refill：

Refill filler = Refill.intervally(5, Duration.ofMinutes(1));

所谓间隔策略指的是每隔一段时间，一次性的填充所有令牌，比如上面的例子，会每隔一分钟，填充 5 个令牌，如下所示：

而贪婪策略会尽可能贪婪的填充令牌，同样是上面的例子，会将一分钟划分成 5 个更小的时间单元，每隔 12 秒，填充 1 个令牌，如下所示：

在了解了 Bucket4j 中的几个核心概念之后，我们再来看看官网介绍的一些特性：

• 基于令牌桶算法
• 高性能，无锁实现
• 不存在精度问题，所有计算都是基于整型的
• 支持通过符合 JCache API 规范的分布式缓存系统实现分布式限流
• 支持为每个 Bucket 设置多个 Bandwidth
• 支持同步和异步 API
• 支持可插拔的监听 API，用于集成监控和日志
• 不仅可以用于限流，还可以用于简单的调度

Bucket4j 提供了丰富的文档，推荐在使用 Bucket4j 之前，先把官方文档中的 基本用法 和 高级特性 仔细阅读一遍。另外，关于 Bucket4j 的使用，推荐这篇文章 Rate limiting Spring MVC endpoints with bucket4j，这篇文章详细的讲解了如何在 Spring MVC 中使用拦截器和 Bucket4j 打造业务无侵入的限流方案，另外还讲解了如何使用 Hazelcast 实现分布式限流；另外，Rate Limiting a Spring API Using Bucket4j 这篇文章也是一份很好的入门教程，介绍了 Bucket4j 的基础知识，在文章的最后还提供了 Spring Boot Starter 的集成方式，结合 Spring Boot Actuator 很容易将限流指标集成到监控系统中。

和 Guava 的限流器相比，Bucket4j 的功能显然要更胜一筹，毕竟 Guava 的目的只是用作通用工具类，而不是用于限流的。使用 Bucket4j 基本上可以满足我们的大多数要求，不仅支持单机限流和分布式限流，而且可以很好的集成监控，搭配 Prometheus 和 Grafana 简直完美。值得一提的是，有很多开源项目譬如 JHipster API Gateway 就是使用 Bucket4j 来实现限流的。

Bucket4j 唯一不足的地方是它只支持请求频率限流，不支持并发量限流，另外还有一点，虽然 Bucket4j 支持分布式限流，但它是基于 Hazelcast 这样的分布式缓存系统实现的，不能使用 Redis，这在很多使用 Redis 作缓存的项目中就很不爽，所以我们还需要在开源的世界里继续探索。

3.3 Resilience4j

Resilience4j 是一款轻量级、易使用的高可用框架。用过 Spring Cloud 早期版本的同学肯定都听过 Netflix Hystrix，Resilience4j 的设计灵感就来自于它。自从 Hystrix 停止维护之后，官方也推荐大家使用 Resilience4j 来代替 Hystrix。

Resilience4j 的底层采用 Vavr，这是一个非常轻量级的 Java 函数式库，使得 Resilience4j 非常适合函数式编程。Resilience4j 以装饰器模式提供对函数式接口或 lambda 表达式的封装，提供了一波高可用机制：重试（Retry）、熔断（Circuit Breaker）、限流（Rate Limiter）、限时（Timer Limiter）、隔离（Bulkhead）、缓存（Caceh） 和 降级（Fallback）。我们重点关注这里的两个功能：限流（Rate Limiter） 和 隔离（Bulkhead），Rate Limiter 是请求频率限流，Bulkhead 是并发量限流。

Resilience4j 提供了两种限流的实现：SemaphoreBasedRateLimiter 和 AtomicRateLimiter。SemaphoreBasedRateLimiter 基于信号量实现，用户的每次请求都会申请一个信号量，并记录申请的时间，申请通过则允许请求，申请失败则限流，另外有一个内部线程会定期扫描过期的信号量并释放，很显然这是令牌桶的算法。AtomicRateLimiter 和上面的经典实现类似，不需要额外的线程，在处理每次请求时，根据距离上次请求的时间和生成令牌的速度自动填充。关于这二者的区别可以参考这篇文章 Rate Limiter Internals in Resilience4j。

Resilience4j 也提供了两种隔离的实现：SemaphoreBulkhead 和 ThreadPoolBulkhead，通过信号量或线程池控制请求的并发数，具体的用法参考官方文档，这里不再赘述。

下面是一个同时使用限流和隔离的例子：

// 创建一个 Bulkhead，最大并发量为 150
BulkheadConfig bulkheadConfig = BulkheadConfig.custom()
    .maxConcurrentCalls(150)
    .maxWaitTime(100)
    .build();
Bulkhead bulkhead = Bulkhead.of("backendName", bulkheadConfig);

// 创建一个 RateLimiter，每秒允许一次请求
RateLimiterConfig rateLimiterConfig = RateLimiterConfig.custom()
    .timeoutDuration(Duration.ofMillis(100))
    .limitRefreshPeriod(Duration.ofSeconds(1))
    .limitForPeriod(1)
    .build();
RateLimiter rateLimiter = RateLimiter.of("backendName", rateLimiterConfig);

// 使用 Bulkhead 和 RateLimiter 装饰业务逻辑
Supplier<String> supplier = () -> backendService.doSomething();
Supplier<String> decoratedSupplier = Decorators.ofSupplier(supplier)
  .withBulkhead(bulkhead)
  .withRateLimiter(rateLimiter)
  .decorate();

// 调用业务逻辑
Try<String> try = Try.ofSupplier(decoratedSupplier);
assertThat(try.isSuccess()).isTrue();

Resilience4j 在功能特性上比 Bucket4j 强大不少，而且还支持并发量限流。不过最大的遗憾是，Resilience4j 不支持分布式限流。

3.4 其他

网上还有很多限流相关的开源项目，不可能一一介绍，这里列出来的只是冰山之一角：

• https://github.com/mokies/ratelimitj
• https://github.com/wangzheng0822/ratelimiter4j
• https://github.com/wukq/rate-limiter
• https://github.com/marcosbarbero/spring-cloud-zuul-ratelimit
• https://github.com/onblog/SnowJena
• https://gitee.com/zhanghaiyang/spring-boot-starter-current-limiting
• https://github.com/Netflix/concurrency-limits

可以看出，限流技术在实际项目中应用非常广泛，大家对实现自己的限流算法乐此不疲，新算法和新实现层出不穷。但是找来找去，目前还没有找到一款开源项目完全满足我的需求。

我的需求其实很简单，需要同时满足两种不同的限流场景：请求频率限流和并发量限流，并且能同时满足两种不同的限流架构：单机限流和分布式限流。下面我们就开始在 Spring Cloud Gateway 中实现这几种限流，通过前面介绍的那些项目，我们取长补短，基本上都能用比较成熟的技术实现，只不过对于最后一种情况，分布式并发量限流，网上没有搜到现成的解决方案，在和同事讨论了几个晚上之后，想出一种新型的基于双窗口滑动的限流算法，我在这里抛砖引玉，欢迎大家批评指正，如果大家有更好的方法，也欢迎讨论。

四、在网关中实现限流

在文章一开始介绍 Spring Cloud Gateway 的特性时，我们注意到其中有一条 Request Rate Limiting，说明网关自带了限流的功能，但是 Spring Cloud Gateway 自带的限流有很多限制，譬如不支持单机限流，不支持并发量限流，而且它的请求频率限流也是不尽人意，这些都需要我们自己动手来解决。

4.1 实现单机请求频率限流

Spring Cloud Gateway 中定义了关于限流的一个接口 RateLimiter，如下：

public interface RateLimiter<C> extends StatefulConfigurable<C> {
    Mono<RateLimiter.Response> isAllowed(String routeId, String id);
}

这个接口就一个方法 isAllowed，第一个参数 routeId 表示请求路由的 ID，根据 routeId 可以获取限流相关的配置，第二个参数 id 表示要限流的对象的唯一标识，可以是用户名，也可以是 IP，或者其他的可以从 ServerWebExchange 中得到的信息。我们看下 RequestRateLimiterGatewayFilterFactory 中对 isAllowed 的调用逻辑：

    @Override
    public GatewayFilter apply(Config config) {
        // 从配置中得到 KeyResolver
        KeyResolver resolver = getOrDefault(config.keyResolver, defaultKeyResolver);
        // 从配置中得到 RateLimiter
        RateLimiter<Object> limiter = getOrDefault(config.rateLimiter,
                defaultRateLimiter);
        boolean denyEmpty = getOrDefault(config.denyEmptyKey, this.denyEmptyKey);
        HttpStatusHolder emptyKeyStatus = HttpStatusHolder
                .parse(getOrDefault(config.emptyKeyStatus, this.emptyKeyStatusCode));

        return (exchange, chain) -> resolver.resolve(exchange).defaultIfEmpty(EMPTY_KEY)
                .flatMap(key -> {
                    // 通过 KeyResolver 得到 key，作为唯一标识 id 传入 isAllowed() 方法
                    if (EMPTY_KEY.equals(key)) {
                        if (denyEmpty) {
                            setResponseStatus(exchange, emptyKeyStatus);
                            return exchange.getResponse().setComplete();
                        }
                        return chain.filter(exchange);
                    }
                    // 获取当前路由 ID，作为 routeId 参数传入 isAllowed() 方法
                    String routeId = config.getRouteId();
                    if (routeId == null) {
                        Route route = exchange
                                .getAttribute(ServerWebExchangeUtils.GATEWAY_ROUTE_ATTR);
                        routeId = route.getId();
                    }
                    return limiter.isAllowed(routeId, key).flatMap(response -> {

                        for (Map.Entry<String, String> header : response.getHeaders()
                                .entrySet()) {
                            exchange.getResponse().getHeaders().add(header.getKey(),
                                    header.getValue());
                        }
                        // 请求允许，直接走到下一个 filter
                        if (response.isAllowed()) {
                            return chain.filter(exchange);
                        }
                        // 请求被限流，返回设置的 HTTP 状态码（默认是 429）
                        setResponseStatus(exchange, config.getStatusCode());
                        return exchange.getResponse().setComplete();
                    });
                });
    }

从上面的逻辑可以看出，通过实现 KeyResolver 接口的 resolve 方法就可以自定义要限流的对象了。

public interface KeyResolver {
    Mono<String> resolve(ServerWebExchange exchange);
}

比如下面的 HostAddrKeyResolver 可以根据 IP 来限流：

public class HostAddrKeyResolver implements KeyResolver {
    @Override
    public Mono<String> resolve(ServerWebExchange exchange) {
        return Mono.just(exchange.getRequest().getRemoteAddress().getAddress().getHostAddress());
    }
}

我们继续看 Spring Cloud Gateway 的代码发现，RateLimiter 接口只提供了一个实现类 RedisRateLimiter：

很显然是基于 Redis 实现的限流，虽说通过 Redis 也可以实现单机限流，但是总感觉有些大材小用，而且对于那些没有 Redis 的环境很不友好。所以，我们要实现真正的本地限流。

我们从 Spring Cloud Gateway 的 pull request 中发现了一个新特性 Feature/local-rate-limiter，而且看提交记录，这个新特性很有可能会合并到 3.0.0 版本中。我们不妨来看下这个 local-rate-limiter 的实现：LocalRateLimiter.java，可以看出它是基于 Resilience4j 实现的：

    public Mono<Response> isAllowed(String routeId, String id) {
        Config routeConfig = loadConfiguration(routeId);

        // How many requests per second do you want a user to be allowed to do?
        int replenishRate = routeConfig.getReplenishRate();

        // How many seconds for a token refresh?
        int refreshPeriod = routeConfig.getRefreshPeriod();

        // How many tokens are requested per request?
        int requestedTokens = routeConfig.getRequestedTokens();

        final io.github.resilience4j.ratelimiter.RateLimiter rateLimiter = RateLimiterRegistry
                .ofDefaults()
                .rateLimiter(id, createRateLimiterConfig(refreshPeriod, replenishRate));

        final boolean allowed = rateLimiter.acquirePermission(requestedTokens);
        final Long tokensLeft = (long) rateLimiter.getMetrics().getAvailablePermissions();

        Response response = new Response(allowed, getHeaders(routeConfig, tokensLeft));
        return Mono.just(response);
    }

有意思的是，这个类 还有一个早期版本，是基于 Bucket4j 实现的：

    public Mono<Response> isAllowed(String routeId, String id) {

        Config routeConfig = loadConfiguration(routeId);

        // How many requests per second do you want a user to be allowed to do?
        int replenishRate = routeConfig.getReplenishRate();

        // How much bursting do you want to allow?
        int burstCapacity = routeConfig.getBurstCapacity();

        // How many tokens are requested per request?
        int requestedTokens = routeConfig.getRequestedTokens();

        final Bucket bucket = bucketMap.computeIfAbsent(id,
                (key) -> createBucket(replenishRate, burstCapacity));

        final boolean allowed = bucket.tryConsume(requestedTokens);

        Response response = new Response(allowed,
                getHeaders(routeConfig, bucket.getAvailableTokens()));
        return Mono.just(response);
    }

实现方式都是类似的，在上面对 Bucket4j 和 Resilience4j 已经作了比较详细的介绍，这里不再赘述。不过从这里也可以看出 Spring 生态圈对 Resilience4j 是比较看好的，我们也可以将其引入到我们的项目中。

4.2 实现分布式请求频率限流

上面介绍了如何实现单机请求频率限流，接下来再看下分布式请求频率限流。这个就比较简单了，因为上面说了，Spring Cloud Gateway 自带了一个限流实现，就是 RedisRateLimiter，可以用于分布式限流。它的实现原理依然是基于令牌桶算法的，不过实现逻辑是放在一段 lua 脚本中的，我们可以在 src/main/resources/META-INF/scripts 目录下找到该脚本文件 request_rate_limiter.lua：

local tokens_key = KEYS[1]
local timestamp_key = KEYS[2]

local rate = tonumber(ARGV[1])
local capacity = tonumber(ARGV[2])
local now = tonumber(ARGV[3])
local requested = tonumber(ARGV[4])

local fill_time = capacity/rate
local ttl = math.floor(fill_time*2)

local last_tokens = tonumber(redis.call("get", tokens_key))
if last_tokens == nil then
  last_tokens = capacity
end

local last_refreshed = tonumber(redis.call("get", timestamp_key))
if last_refreshed == nil then
  last_refreshed = 0
end

local delta = math.max(0, now-last_refreshed)
local filled_tokens = math.min(capacity, last_tokens+(delta*rate))
local allowed = filled_tokens >= requested
local new_tokens = filled_tokens
local allowed_num = 0
if allowed then
  new_tokens = filled_tokens - requested
  allowed_num = 1
end

if ttl > 0 then
  redis.call("setex", tokens_key, ttl, new_tokens)
  redis.call("setex", timestamp_key, ttl, now)
end

return { allowed_num, new_tokens }

这段代码和上面介绍令牌桶算法时用 Java 实现的那段经典代码几乎是一样的。这里使用 lua 脚本，主要是利用了 Redis 的单线程特性，以及执行 lua 脚本的原子性，避免了并发访问时可能出现请求量超出上限的现象。想象目前令牌桶中还剩 1 个令牌，此时有两个请求同时到来，判断令牌是否足够也是同时的，两个请求都认为还剩 1 个令牌，于是两个请求都被允许了。

有两种方式来配置 Spring Cloud Gateway 自带的限流。第一种方式是通过配置文件，比如下面所示的代码，可以对某个 route 进行限流：

spring:
  cloud:
    gateway:
      routes:
      - id: test
        uri: http://httpbin.org:80/get
        filters:
        - name: RequestRateLimiter
          args:
            key-resolver: '#{@hostAddrKeyResolver}'
            redis-rate-limiter.replenishRate: 1
            redis-rate-limiter.burstCapacity: 3

其中，key-resolver 使用 SpEL 表达式 #{@beanName} 从 Spring 容器中获取 hostAddrKeyResolver 对象，burstCapacity 表示令牌桶的大小，replenishRate 表示每秒往桶中填充多少个令牌，也就是填充速度。

第二种方式是通过下面的代码来配置：

@Bean
public RouteLocator myRoutes(RouteLocatorBuilder builder) {
  return builder.routes()
    .route(p -> p
      .path("/get")
      .filters(filter -> filter.requestRateLimiter()
        .rateLimiter(RedisRateLimiter.class, rl -> rl.setBurstCapacity(3).setReplenishRate(1)).and())
      .uri("http://httpbin.org:80"))
    .build();
}

这样就可以对某个 route 进行限流了。但是这里有一点要注意，Spring Cloud Gateway 自带的限流器有一个很大的坑，replenishRate 不支持设置小数，也就是说往桶中填充的 token 的速度最少为每秒 1 个，所以，如果我的限流规则是每分钟 10 个请求（按理说应该每 6 秒填充一次，或每秒填充 1/6 个 token），这种情况 Spring Cloud Gateway 就没法正确的限流。网上也有人提了 issue，support greater than a second resolution for the rate limiter，但还没有得到解决。

4.3 实现单机并发量限流

上面学习 Resilience4j 的时候，我们提到了 Resilience4j 的一个功能特性，叫 隔离（Bulkhead）。Bulkhead 这个单词的意思是船的舱壁，利用舱壁可以将不同的船舱隔离起来，这样如果一个船舱破损进水，那么只损失这一个船舱，其它船舱可以不受影响。借鉴造船行业的经验，这种模式也被引入到软件行业，我们把它叫做 舱壁模式（Bulkhead pattern）。舱壁模式一般用于服务隔离，对于一些比较重要的系统资源，如 CPU、内存、连接数等，可以为每个服务设置各自的资源限制，防止某个异常的服务把系统的所有资源都消耗掉。这种服务隔离的思想同样可以用来做并发量限流。

正如前文所述，Resilience4j 提供了两种 Bulkhead 的实现：SemaphoreBulkhead 和 ThreadPoolBulkhead，这也正是舱壁模式常见的两种实现方案：一种是带计数的信号量，一种是固定大小的线程池。考虑到多线程场景下的线程切换成本，默认推荐使用信号量。

在操作系统基础课程中，我们学习过两个名词：互斥量（Mutex） 和 信号量（Semaphores）。互斥量用于线程的互斥，它和临界区有点相似，只有拥有互斥对象的线程才有访问资源的权限，由于互斥对象只有一个，因此任何情况下只会有一个线程在访问此共享资源，从而保证了多线程可以安全的访问和操作共享资源。而信号量是用于线程的同步，这是由荷兰科学家 E.W.Dijkstra 提出的概念，它和互斥量不同，信号允许多个线程同时使用共享资源，但是它同时设定了访问共享资源的线程最大数目，从而可以进行并发量控制。

下面是使用信号量限制并发访问的一个简单例子：

public class SemaphoreTest {

    private static ExecutorService threadPool = Executors.newFixedThreadPool(100);
    private static Semaphore semaphore = new Semaphore(10);

    public static void main(String[] args) {
        for (int i = 0; i < 100; i++) {
            threadPool.execute(new Runnable() {
                @Override
                public void run() {
                    try {
                        semaphore.acquire();
                        System.out.println("Request processing ...");
                        semaphore.release();
                    } catch (InterruptedException e) {
                        e.printStack();
                    }
                }
            });
        }
        threadPool.shutdown();
    }
}

这里我们创建了 100 个线程同时执行，但是由于信号量计数为 10，所以同时只能有 10 个线程在处理请求。说到计数，实际上，在 Java 里除了 Semaphore 还有很多类也可以用作计数，比如 AtomicLong 或 LongAdder，这在并发量限流中非常常见，只是无法提供像信号量那样的阻塞能力：

public class AtomicLongTest {

    private static ExecutorService threadPool = Executors.newFixedThreadPool(100);
    private static AtomicLong atomic = new AtomicLong();

    public static void main(String[] args) {
        for (int i = 0; i < 100; i++) {
            threadPool.execute(new Runnable() {
                @Override
                public void run() {
                    try {
                        if(atomic.incrementAndGet() > 10) {
                            System.out.println("Request rejected ...");
                            return;
                        }
                        System.out.println("Request processing ...");
                        atomic.decrementAndGet();
                    } catch (InterruptedException e) {
                        e.printStack();
                    }
                }
            });
        }
        threadPool.shutdown();
    }
}

4.4 实现分布式并发量限流

通过在单机实现并发量限流，我们掌握了几种常用的手段：信号量、线程池、计数器，这些都是单机上的概念。那么稍微拓展下，如果能实现分布式信号量、分布式线程池、分布式计数器，那么实现分布式并发量限流不就易如反掌了吗？

关于分布式线程池，是我自己杜撰的词，在网上并没有找到类似的概念，比较接近的概念是资源调度和分发，但是又感觉不像，这里直接忽略吧。

关于分布式信号量，还真有这样的东西，比如 Apache Ignite 就提供了 IgniteSemaphore 用于创建分布式信号量，它的使用方式和 Semaphore 非常类似，参考这里。使用 Redis 的 ZSet 也可以实现分布式信号量，比如 这篇博客介绍的方法，还有《Redis in Action》这本电子书中也提到了这样的例子，教你如何实现 Counting semaphores。另外，Redisson 也实现了基于 Redis 的分布式信号量 RSemaphore，用法也和 Semaphore 类似。使用分布式信号量可以很容易实现分布式并发量限流，实现方式和上面的单机并发量限流几乎是一样的。

最后，关于分布式计数器，实现方案也是多种多样。比如使用 Redis 的 INCR 就很容易实现，更有甚者，使用 MySQL 数据库也可以实现。只不过使用计数器要注意操作的原子性，每次请求时都要经过这三步操作：取计数器当前的值、判断是否超过阈值，超过则拒绝、将计数器的值自增。这其实和信号量的 P 操作是一样的，而释放就对应 V 操作。

所以，利用分布式信号量和计数器就可以实现并发量限流了吗？问题当然没有这么简单。实际上，上面通过信号量和计数器实现单机并发量限流的代码片段有一个严重 BUG：

                        semaphore.acquire();
                        System.out.println("Request processing ...");
                        semaphore.release();

想象一下如果在处理请求时出现异常了会怎么样？很显然，信号量被该线程获取了，但是却永远不会释放，如果请求异常多了，这将导致信号量被占满，最后一个请求也进不来。在单机场景下，这个问题可以很容易解决，加一个 finally 就行了：

                    try {
                        semaphore.acquire();
                        System.out.println("Request processing ...");
                    } catch (InterruptedException e) {
                        e.printStack();
                    } finally {
                        semaphore.release();
                    }

由于无论出现何种异常，finally 中的代码一定会执行，这样就保证了信号量一定会被释放。但是在分布式系统中，就不是加一个 finally 这么简单了。这是因为在分布式系统中可能存在的异常不一定是可被捕获的代码异常，还有可能是服务崩溃或者不可预知的系统宕机，就算是正常的服务重启也可能导致分布式信号量无法释放。

对于这个问题，我和几个同事连续讨论了几个晚上，想出了两种解决方法：第一种方法是使用带 TTL 的计数器，第二种方法是基于双窗口滑动的一种比较 tricky 的算法。

第一种方法比较容易理解，我们为每个请求赋予一个唯一 ID，并在 Redis 里写入一个键值对，key 为 requests_xxx（xxx 为请求 ID），value 为 1，并给这个 key 设置一个 TTL（如果你的应用中存在耗时非常长的请求，譬如对于一些 WebSockket 请求可能会持续几个小时，还需要开一个线程定期去刷新这个 key 的 TTL）。然后在判断并发量时，使用 KEYS 命令查询 requests_* 开头的 key 的个数，就可以知道当前一共有多少个请求，如果超过并发量上限则拒绝请求。这种方法可以很好的应对服务崩溃或重启的问题，由于每个 key 都设置了 TTL，所以经过一段时间后，这些 key 就会自动消失，就不会出现信号量占满不释放的情况了。但是这里使用 KEYS 命令查询请求个数是一个非常低效的做法，在请求量比较多的情况下，网关的性能会受到严重影响。我们可以把 KEYS 命令换成 SCAN，性能会得到些许提升，但总体来说效果还是很不理想的。

针对第一种方法，我们可以进一步优化，不用为每个请求写一个键值对，而是为每个分布式系统中的每个实例赋予一个唯一 ID，并在 Redis 里写一个键值对，key 为 instances_xxx（xxx 为实例 ID），value 为这个实例当前的并发量。同样的，我们为这个 key 设置一个 TTL，并且开启一个线程定期去刷新这个 TTL。每接受一个请求后，计数器加一，请求结束，计数器减一，这和单机场景下的处理方式一样，只不过在判断并发量时，还是需要使用 KEYS 或 SCAN 获取所有的实例，并计算出并发量的总和。不过由于实例个数是有限的，性能比之前的做法有了明显的提升。

第二种方法我称之为 双窗口滑动算法，结合了 TTL 计数器和滑动窗口算法。我们按分钟来设置一个时间窗口，在 Redis 里对应 202009051130 这样的一个 key，value 为计数器，表示请求的数量。当接受一个请求后，在当前的时间窗口中加一，当请求结束，在当前的时间窗口中减一，注意，接受请求和请求结束的时间窗口可能不是同一个。另外，我们还需要一个本地列表来记录当前实例正在处理的所有请求和请求对应的时间窗口，并通过一个小于时间窗口的定时线程（如 30 秒）来迁移过期的请求，所谓过期，指的是请求的时间窗口和当前时间窗口不一致。那么具体如何迁移呢？我们首先需要统计列表中一共有多少请求过期了，然后将列表中的过期请求时间更新为当前时间窗口，并从 Redis 中上一个时间窗口移动相应数量到当前时间窗口，也就是上一个时间窗口减 X，当前时间窗口加 X。由于迁移线程定期执行，所以过期的请求总是会被移动到当前窗口，最终 Redis 中只有当前时间窗口和上个时间窗口这两个时间窗口中有数据，再早一点的窗口时间中的数据会被往后迁移，所以可以给这个 key 设置一个 3 分钟或 5 分钟的 TTL。判断并发量时，由于只有两个 key，只需要使用 MGET 获取两个值相加即可。下面的流程图详细描述了算法的运行过程：

其中有几个需要注意的细节：

1. 请求结束时，直接在 Redis 中当前时间窗口减一即可，就算是负数也没关系。请求列表中的该请求不用急着删除，可以打上结束标记，在迁移线程中统一删除（当然，如果请求的开始时间和结束时间在同一个窗口，可以直接删除）；
2. 迁移的时间间隔要小于时间窗口，一般设置为 30s；
3. Redis 中的 key 一定要设置 TTL，时间至少为 2 个时间窗口，一般设置为 3 分钟；
4. 迁移过程涉及到“从上一个时间窗口减”和“在当前时间窗口加”两个操作，要注意操作的原子性；
5. 获取当前并发量可以通过 MGET 一次性读取两个时间窗口的值，不用 GET 两次；
6. 获取并发量和判断并发量是否超限，这个过程也要注意操作的原子性。

总结

网关作为微服务架构中的重要一环，充当着一夫当关万夫莫开的角色，所以对网关服务的稳定性要求和性能要求都非常高。为保证网关服务的稳定性，一代又一代的程序员们前仆后继，想出了十八般武艺：限流、熔断、隔离、缓存、降级、等等等等。这篇文章从限流入手，详细介绍了限流的场景和算法，以及源码实现和可能踩到的坑。尽管限流只是网关的一个非常小的功能，但却影响到网关的方方面面，在系统架构的设计中至关重要。虽然我试着从不同的角度希望把限流介绍的更完全，但终究是管中窥豹，只见一斑，还有很多的内容没有介绍到，比如阿里开源的 Sentinel 组件也可以用于限流，因为篇幅有限未能展开。另外前文提到的 Netflix 不再维护 Hystrix 项目，这是因为他们把精力放到另一个限流项目 concurrency-limits 上了，这个项目的目标是打造一款自适应的，极具弹性的限流组件，它借鉴了 TCP 拥塞控制的算法（TCP congestion control algorithm），实现系统的自动限流，感兴趣的同学可以去它的项目主页了解更多内容。

本文篇幅较长，难免疏漏，如有问题，还望不吝赐教。

参考

1. 微服务网关实战——Spring Cloud Gateway
2. 《亿级流量网站架构核心技术》张开涛
3. 聊聊高并发系统之限流特技
4. 架构师成长之路之限流
5. 微服务接口限流的设计与思考
6. 常用4种限流算法介绍及比较
7. 来谈谈限流-从概念到实现
8. 高并发下的限流分析
9. 计数器算法
10. 基于Redis的限流系统的设计
11. API 调用次数限制实现
12. Techniques to Improve QoS
13. An alternative approach to rate limiting
14. Scaling your API with rate limiters
15. Brief overview of token-bucket algorithm
16. Rate limiting Spring MVC endpoints with bucket4j
17. Rate Limiter Internals in Resilience4j
18. 高可用框架Resilience4j使用指南
19. 阿里巴巴开源限流系统 Sentinel 全解析
20. spring cloud gateway 之限流篇
21. 服务容错模式
22. 你的API会自适应「弹性」限流吗?