### Squirrel-Foundation 状态机开源项目介绍
**Squirrel-Foundation** 是一个轻量级、灵活、可扩展、易于使用且类型安全的 Java 状态机实现，适用于企业级应用。它提供了多种方式来定义状态机，包括注解声明和 Fluent API，并且支持状态转换、状态动作、上下文传递等功能。
#### GitHub 地址
- **项目地址**：[https://github.com/hekailiang/squirrel](https://github.com/hekailiang/squirrel)
#### 使用说明
##### 1. 添加依赖
Squirrel-Foundation 已发布到 Maven 中央仓库，可以通过以下方式添加依赖：
- **最新发布版本**：
```xml
<dependency>
<groupId>org.squirrelframework</groupId>
<artifactId>squirrel-foundation</artifactId>
<version>0.3.10</version>
</dependency>
```
- **最新快照版本**：
```xml
<dependency>
<groupId>org.squirrelframework</groupId>
<artifactId>squirrel-foundation</artifactId>
<version>0.3.11-SNAPSHOT</version>
</dependency>
```
##### 2. 快速开始
以下是一个简单的示例代码，展示如何创建和使用状态机：
```java
public class QuickStartSample {
// 定义状态机事件
enum FSMEvent {
ToA, ToB, ToC, ToD
}
// 定义状态机类
@StateMachineParameters(stateType = String.class, eventType = FSMEvent.class, contextType = Integer.class)
static class StateMachineSample extends AbstractUntypedStateMachine {
protected void fromAToB(String from, String to, FSMEvent event, Integer context) {
System.out.println("Transition from '" + from + "' to '" + to + "' on event '" + event +
"' with context '" + context + "'.");
}
protected void ontoB(String from, String to, FSMEvent event, Integer context) {
System.out.println("Entry State '" + to + "'.");
}
}
public static void main(String[] args) {
// 构建状态转换
UntypedStateMachineBuilder builder = StateMachineBuilderFactory.create(StateMachineSample.class);
builder.externalTransition().from("A").to("B").on(FSMEvent.ToB).callMethod("fromAToB");
builder.onEntry("B").callMethod("ontoB");
// 使用状态机
UntypedStateMachine fsm = builder.newStateMachine("A");
fsm.fire(FSMEvent.ToB, 10);
System.out.println("Current state is " + fsm.getCurrentState());
}
}
```
##### 3. 定义状态机
Squirrel-Foundation 支持通过 Fluent API 和注解声明两种方式定义状态机：
- **Fluent API**：
```java
builder.externalTransition().from(MyState.A).to(MyState.B).on(MyEvent.GoToB);
```
- **注解声明**：
```java
@States({
@State(name = "A", entryCallMethod = "entryStateA", exitCallMethod = "exitStateA"),
@State(name = "B", entryCallMethod = "entryStateB", exitCallMethod = "exitStateB")
})
@Transitions({
@Transit(from = "A", to = "B", on = "GoToB", callMethod = "stateAToStateBOnGotoB"),
@Transit(from = "A", to = "A", on = "WithinA", callMethod = "stateAToStateAOnWithinA", type = TransitionType.INTERNAL)
})
interface MyStateMachine extends StateMachine<MyStateMachine, MyState, MyEvent, MyContext> {
void entryStateA(MyState from, MyState to, MyEvent event, MyContext context);
void stateAToStateBOnGotoB(MyState from, MyState to, MyEvent event, MyContext context);
void stateAToStateAOnWithinA(MyState from, MyState to, MyEvent event, MyContext context);
void exitStateA(MyState from, MyState to, MyEvent event, MyContext context);
}
```
##### 4. 高级特性
- **转换扩展方法**：可以在状态转换时扩展自定义逻辑。
```java
protected void afterTransitionCompleted(S fromState, S toState, E event, C context) {
// 自定义逻辑
}
```
- **异步事件处理**：通过 `@AsyncExecute` 注解可以将事件处理逻辑异步执行。
```java
public class DeclarativeListener {
@OnTransitionBegin
@AsyncExecute
public void onTransitionBegin(...) {
// 异步处理逻辑
}
}
```
##### 5. 与其他框架集成
Squirrel-Foundation 可以与 Spring 框架集成，通过注册一个后处理器来自动注入依赖：
```java
@Component
public class StateMachineAutowireProcessor implements SquirrelPostProcessor<StateMachine>, ApplicationContextAware {
private ApplicationContext applicationContext;
public StateMachineAutowireProcessor() {
SquirrelPostProcessorProvider.getInstance().register(StateMachine.class, this);
}
@Override
public void postProcess(StateMachine stateMachine) {
AutowireCapableBeanFactory autowireCapableBeanFactory = applicationContext.getAutowireCapableBeanFactory();
autowireCapableBeanFactory.autowireBean(stateMachine);
}
@Override
public void setApplicationContext(ApplicationContext applicationContext) throws BeansException {
this.applicationContext = applicationContext;
}
}
```
更多使用细节和高级特性可以参考 [Squirrel-Foundation 官方文档](https://hekailiang.github.io/squirrel/) 或其 [GitHub 仓库](https://github.com/hekailiang/squirrel)。
