前言

众所周知 Spring Boot 是一个「开箱即用」、「约定大于配置」的框架，这得益于 Spring Boot 提供的大量开箱即用的 Starter，而本文将介绍如何编写一个自定义的 Spring Boot Starter。

本文尝试以一个 IP 地址定位库 Ip2region 为例，将其使用 starter 的方式引入到项目中。

创建 Maven 项目

<project ...>
    <modelVersion>4.0.0</modelVersion>

    <groupId>cn.nipx</groupId>
    <artifactId>ip2region-spring-boot-starter</artifactId>
    <version>0.0.1-SNAPSHOT</version>

    <properties>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        <ip2region.version>2.7.0</ip2region.version>
        <spring-boot.version>2.2.6.RELEASE</spring-boot.version>
    </properties>

    <dependencies>

        <!-- Spring Boot Starter -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter</artifactId>
            <version>${spring-boot.version}</version>
        </dependency>

        <!-- 依赖 -->
        <dependency>
            <groupId>org.lionsoul</groupId>
            <artifactId>ip2region</artifactId>
            <version>2.7.0</version>
        </dependency>

    </dependencies>

</project>

• artifactId：使用 -spring-boot-starter

创建配置属性类

略，本 Starter 用不到，跟正常的 Spring Boot 项目配置属性类一样。

参考示例：

@ConfigurationProperties(prefix = "haodanku")
@Data
public class HaodankuProperties {

    private String apikey;

}

创建配置类

@AutoConfiguration
public class Ip2regionAutoConfiguration {

	@Bean
	public Searcher searcher(ResourceLoader resourceLoader) {

		try {
			// 1、加载整个 xdb 到内存。  
			Resource resource = resourceLoader.getResource("classpath:ip2region.xdb");
			byte[] cBuff = FileCopyUtils.copyToByteArray(resource.getInputStream());

			// 2、使用上述的 cBuff 创建一个完全基于内存的查询对象。
			return Searcher.newWithBuffer(cBuff);
		} catch (IOException e) {
			throw new RuntimeException(e);
		}
	}

	@Bean
	public IpUtil ipUtil(Searcher searcher) {
		return new IpUtil(searcher);
	}

}

笔记

• 在编写自动配置类时，当他是一个普通的 Spring Boot 配置类对待即可。

• 在旧版的 Spring Boot 中 @AutoConfiguration 修改为 @Configuration

• 如果使用到配置注入，则在 AutoConfiguration 类上添加注解 @EnableConfigurationProperties(XxxProperties.class) ，并在用到的 Bean 方法入参中注入。

自动注入配置

当前写法：Spring Boot ≥ 2.7

创建在 src/main/resources/META-INF 下，文件名为 org.springframework.boot.autoconfigure.AutoConfiguration.imports ：

org.springblade.core.ip.config.Ip2regionAutoConfiguration
org.springblade.core.ip.config.Ip2regionAutoConfiguration2
...

笔记

每行编写要注入的类全路径

过时写法：Spring Boot < 2.7

创建在 src/main/resources/META-INF 下，文件名为 spring.factories ：

org.springframework.boot.autoconfigure.EnableAutoConfiguration=\
  org.springblade.core.ip.config.Ip2regionAutoConfiguration

笔记

从第二行开始编写要注入的类全路径，如有多个时用 , 隔开，换行时尾部添加 \

测试

注意

这并不是一个标准的测试方法

创建一个 Applicant 类

@SpringBootApplication
public class SampleApplication implements CommandLineRunner {

	@Autowired
	private IpUtil ipUtil;


	public static void main(String[] args) {
		SpringApplication.run(SampleApplication.class, args);
	}

	public void run(String... args) throws Exception {
		System.out.println(ipUtil.parseRegion("127.0.0.1"));
		System.out.println(ipUtil.parseRegion("114.114.114.114"));
		System.out.println(ipUtil.parseRegion("113.119.181.48"));
	}
}

正常输出则为正常

总结

• Starter 的核心是 spring.factories 文件，其他与在普通的 Spring Boot 项目注入、配置一样，区别在于普通的 Spring Boot 项目会自动扫描启动类所在包路径下所有子包的配置，而 Starter 则需要通过 spring.factories 来指明哪个配置文件时需要

参考资料

• Creating a Custom Starter with Spring Boot | Baeldung (opens new window)
• SpringBoot 进阶 - 自定义 starter | Java 全栈知识体系 (opens new window)