15.SpringShell源码分析-命令扫描与执行

上篇从源码分析了SpringShell的ApplicationRunner, 本文笔者从源码分析一下自定义命令的扫描和解析过程.

1. 解析自定义命令

1.1 注入Shell 组件

SpringShell 会在SpringShellAutoConfiguration 配置类中使用@Bean 方式向Spring 容器中注入Shell 组件.

// 源码:org.springframework.shell.SpringShellAutoConfiguration
@Configuration
@Import(ResultHandlerConfig.class)
public class SpringShellAutoConfiguration {

    // 省略其它bean...
    
	@Bean
	public Shell shell(@Qualifier("main") ResultHandler resultHandler) {
		return new Shell(resultHandler);
	}

}

1.2 执行Shell 初始化方法, 完成自定义命令解析工作

由于Shell 类定义时, 使用JSR250注解@PostConstruct 定义了对象初始化方法, 因此在Spring 容器创建Shell 实例之后, 会执行shell实例的gatherMethodTargets()方法来完成自定义命令的解析工作.

1. 创建ConfigurableCommandRegistry, 用于在注册命令时, 临时存储所有自定义命令和方法的映射关系.
2. 获取所有的目标方法注册器, 会获取到StandardMethodTargetRegistrar 对象, 调用其register 方法, 此方法会将解析到的所有命令方法注册到ConfigurableCommandRegistry中
3. 获取已注册的所有命令, 保存在methodTargets 属性中, 用于后续使用.
4. 对所有命令对应的方法做参数校验

// 源码: org.springframework.shell.Shell#gatherMethodTargets
@PostConstruct
public void gatherMethodTargets() throws Exception {
    // 创建ConfigurableCommandRegistry, 存储所有命令与方法的映射关系.
	ConfigurableCommandRegistry registry = new ConfigurableCommandRegistry();
	
	// 获取所有的目标方法注册器, 会获取到StandardMethodTargetRegistrar
	for (MethodTargetRegistrar resolver : applicationContext.getBeansOfType(MethodTargetRegistrar.class).values()) {
	    // 调用StandardMethodTargetRegistrar 的register 方法, 将扫描到的所有命令注册到 ConfigurableCommandRegistry 中
		resolver.register(registry);
	}
	// 获取ConfigurableCommandRegistry 中已注册的所有命令, 存入属性变量methodTargets 中, 类型为:　Map<String, MethodTarget>
	methodTargets = registry.listCommands();
	
	// 对所有命令做参数校验
	methodTargets.values().forEach(this::validateParameterResolvers);
}

1.3 解析所有ShellComponent组件, 注册自定义命令

1. 从IOC容器中获取所有使用@ShellComponent定义的组件.
2. 遍历解析所有ShellComponent组件, 对每个组件的ShellMehtod 方法进行遍历
3. 处理命令别名, 将驼峰风格修改为-连接方式. 如addInt 别名为add-int
4. 处理命令组名, 优先使用方法定义的组名, 其次是类指定的组名, 再次是包指定的组名, 最后是默认的组名
5. 遍历所有别名, 对每个别名进行注册
   1. 获取限制命令是否可用的指示器
   2. 创建命令映射对象MethodTarget
   3. 将命令注册到ConfigurableCommandRegistry中, 即存储在ConfigurableCommandRegistry的map中
   4. 同时也将命令添加到属性commands中, toString中使用.

//　源码：org.springframework.shell.standard.StandardMethodTargetRegistrar#register
@Override
public void register(ConfigurableCommandRegistry registry) {
    // 通过注解类型方式, 获取容器中所有使用@ShellComponet 注解修饰的组件
	Map<String, Object> commandBeans = applicationContext.getBeansWithAnnotation(ShellComponent.class);
	
	// 遍历所有的ShellComponet 组件
	for (Object bean : commandBeans.values()) {
		Class<?> clazz = bean.getClass();
		// 反射处理ShellComponet 组件中的所有使用@ShellMethod 注解修饰的方法方法
		ReflectionUtils.doWithMethods(clazz, method -> {
		    
			ShellMethod shellMapping = method.getAnnotation(ShellMethod.class);
			
			// 处理方法别名, 即@ShellMethod 的key属性
			String[] keys = shellMapping.key();
			if (keys.length == 0) {
			    // 对别名做转换, 将驼峰风格修改为使用-连接的方式
				keys = new String[] { Utils.unCamelify(method.getName()) };
			}
			
			// 获取组名: 会先判断方法是否指定了组名, 否则判断类是否定义了组名, 否则判断包是否定义了组名, 否则返回默认组名
			String group = getOrInferGroup(method);
			
			// 遍历所有的别名, 每个别名都注册一次
			for (String key : keys) {
			    // 获取所有的限制是否可用的指示器
				Supplier<Availability> availabilityIndicator = findAvailabilityIndicator(keys, bean, method);
				
				// 创建命令对应的MethodTarget
				MethodTarget target = new MethodTarget(method, bean, new Command.Help(shellMapping.value(), group), availabilityIndicator);
				
				// 将命令注册到ConfigurableCommandRegistry 中
				registry.register(key, target);
				
				// 也将命令添加到属性commands中, toString中使用
				commands.put(key, target);
			}
		}, method -> method.getAnnotation(ShellMethod.class) != null);
	}
}

2. Shell 交互式命令运行逻辑

从笔者上一篇博客中, 我们知道SpringShell启动之后, 会调用ApplicationRunner的run方法来启动应用, 而run方法核心就是调用Shell.run()方法.Shell的run方法是一个循环, 会一直从ApplicationRunner 提供的InputProvider中获取命令, 并执行, 直到获取的命令为null时, 终止循环, 结束程序运行.

2.1 核心循环流程

1. 创建变量result, 保存命令执行结果
2. 启动循环, 循环终止条件为:
   1. 返回结果为ExitRequest实例时, 当执行quite/exit命令时, 返回ExitRequest.　参阅源码: org.springframework.shell.standard.commands.Quit#quit
   2. 当从InputProvider中读取返回值为null 时, 通过break跳出循环
3. 从InputProvider中获取一条输入命令
4. 判断InputProvider.readInput()返回值是否为null, 是的话直接跳出循环
5. 调用evaluate方法, 执行命令, 获取命令返回值
6. 判断返回结果, 如果返回结果正常, 则处理返回结果.

public void run(InputProvider inputProvider) throws IOException {
    // 自定义保存命令执行结果
	Object result = null;

	// 无限循环, 知道result为退出嘛
	while (!(result instanceof ExitRequest)) {
		Input input;

		// 从输入源中读取一条输入
		try {
			input = inputProvider.readInput();
		}
		catch (Exception e) {
			resultHandler.handleResult(e);
			continue;
		}

		// 当读取的输入为null时, 跳出循环, 结束此shell的运行
		if (input == null) {
			break;
		}

		// 执行命令, 返回执行结果
		result = evaluate(input);

		// 结果不是new Object 或 ExitRequest 实例时, 处理结果
		if (result != NO_INPUT && !(result instanceof ExitRequest)) {
			resultHandler.handleResult(result);
		}
	}
}

2.2 执行命令逻辑

1. 输入命令为空, 则返回new Object
2. 格式化命令, 将命令中多余的空白符,都替换为单个空格
3. 提取输入命令中的命令(不带参数的)
4. 将输入命令按空格分隔成数组
5. 如果命令不为空:
   1. 从shell.methodTargets 属性中获取命令的映射关系
   2. 获取命令的限制可用条件, 用于判断当前命令是否可执行
      1. 如果命令可执行:
         1. 获取命令的参数
         2. 获取命令对应的方法
         3. 解析并校验命令传入的参数
         4. 反射调用命令对应的方法, 并返回方法返回值
      2. 命令不可执行, 则返回命令不可用异常信息
6. 命令找不到, 返回无此命令的异常信息.

// 源码:org.springframework.shell.Shell#evaluate
// 假定传入参数为  add    2    3
public Object evaluate(Input input) {
    // 如果input 为空, 返回New Object()
	if (noInput(input)) {
		return NO_INPUT;
	}

    // 格式化命令, 将多个空格转换为单个空格. 转化后line为add 2 3
	String line = input.words().stream().collect(Collectors.joining(" ")).trim();
	
	// 从命令中提取命令的key, command为add
	String command = findLongestCommand(line);

    // 将输入的命令按空白符分隔为列表, words为: ["add","2","3"]
	List<String> words = input.words();
	if (command != null) {
	    // 从shell.methodTarget 中获取命令对应的方法信息
		MethodTarget methodTarget = methodTargets.get(command);
		// 获取限制命令是否可用的条件定义
		Availability availability = methodTarget.getAvailability();
		
		// 判断命令是否可用
		if (availability.isAvailable()) {
		    // 获取命令参数, wordsForArgs 为["2","3"]
			List<String> wordsForArgs = wordsForArguments(command, words);
			
			// 获取命令对应的方法
			Method method = methodTarget.getMethod();

			try {
			    // 解析校验参数
				Object[] args = resolveArgs(method, wordsForArgs);
				validateArgs(args, methodTarget);
				
				// 反射调用方法, 并返回方法返回值
				return ReflectionUtils.invokeMethod(method, methodTarget.getBean(), args);
			}
			catch (Exception e) {
				return e;
			}
		} else {
		    //命令不可用, 返回命令不可用异常. CommandNotCurrentlyAvailable 继承了 RuntimeException
			return new CommandNotCurrentlyAvailable(command, availability);
		}
	} else {
	    // 命令找不到, 返回命令找不到异常.CommandNotFound 继承了 RuntimeException
		return new CommandNotFound(words);
	}
}