feat: enhance FastProto with annotation processor.

Author: Deng-Ran

.gitignore

@@ -24,8 +24,10 @@ hs_err_pid*
 
 # IDE Files
 .idea/
-/target
-fastproto.iml
+*.iml
+
+# Maven build output
+target/
 
 # Development notes
 dev_note.md

CHANGELOG-zh.md

@@ -2,6 +2,51 @@
 
 本文件用于记录本项目的所有重要变更。
 
+## [4.0.0] - 2026-01-26
+### 重大变更
+- **多模块重构**：项目拆分为两个模块：
+  - `fastproto` - 核心库，包含所有运行时功能（artifactId 保持向后兼容）
+  - `fastproto-processor` - 注解处理器，用于编译时公式类生成
+- 动态 lambda 编译默认禁用，以提升 Android/JRE 兼容性
+
+### 新增
+- `fastproto-processor` 模块，支持 SPI 自动发现注解处理器
+- `FormulaProcessor` - 在编译时为 `@DecodingFormula(lambda="...")` 和 `@EncodingFormula(lambda="...")` 生成 `Function` 实现类
+- `CodecProcessor` - 为 `@GenerateCodec` 注解的类生成编解码包装器
+- `FormulaRegistry` - 运行时查找编译时生成的公式类
+- 通过注解处理器实现完整的 Android 和 Java 11+ JRE 兼容性
+
+### 变更
+- Lambda 公式现在使用编译时代码生成，而非运行时动态编译
+- 使用 lambda 公式功能需要添加 `fastproto-processor` 依赖
+- 更新文档以反映新的多模块结构
+
+### 升级指南
+从 3.x 升级的用户：
+
+**Maven:**
+```xml
+<dependency>
+    <groupId>org.indunet</groupId>
+    <artifactId>fastproto</artifactId>
+    <version>4.0.0</version>
+</dependency>
+<!-- 使用 lambda 公式时添加 -->
+<dependency>
+    <groupId>org.indunet</groupId>
+    <artifactId>fastproto-processor</artifactId>
+    <version>4.0.0</version>
+    <scope>provided</scope>
+</dependency>
+```
+
+**Gradle:**
+```groovy
+implementation 'org.indunet:fastproto:4.0.0'
+// 使用 lambda 公式时添加
+annotationProcessor 'org.indunet:fastproto-processor:4.0.0'
+```
+
 ## [3.12.3] - 2025-11-23
 ### 新增
 - 新增 `@BcdType` 注解与 `BcdCodec`，支持定长 packed BCD 整数（支持大小端），映射到 `int` / `Integer` 类型。

CHANGELOG.md

@@ -2,6 +2,51 @@
 
 All notable changes to this project will be documented in this file.
 
+## [4.0.0] - 2026-01-26
+### Breaking Changes
+- **Multi-module restructure**: Project split into two modules:
+  - `fastproto` - Core library with all runtime functionality (backwards compatible artifactId)
+  - `fastproto-processor` - Annotation processor for compile-time formula generation
+- Dynamic lambda compilation is now disabled by default for better Android/JRE compatibility
+
+### Added
+- `fastproto-processor` module with SPI auto-discovery for annotation processors
+- `FormulaProcessor` - Generates `Function` classes at compile time for `@DecodingFormula(lambda="...")` and `@EncodingFormula(lambda="...")`
+- `CodecProcessor` - Generates codec wrapper classes for `@GenerateCodec` annotated classes
+- `FormulaRegistry` - Runtime lookup for compile-time generated formula classes
+- Full Android and Java 11+ JRE compatibility for lambda formulas via annotation processor
+
+### Changed
+- Lambda formulas now use compile-time code generation instead of runtime dynamic compilation
+- Users need to add `fastproto-processor` as a dependency to use lambda formula features
+- Updated documentation for new multi-module structure
+
+### Migration Guide
+For users upgrading from 3.x:
+
+**Maven:**
+```xml
+<dependency>
+    <groupId>org.indunet</groupId>
+    <artifactId>fastproto</artifactId>
+    <version>4.0.0</version>
+</dependency>
+<!-- Add if using lambda formulas -->
+<dependency>
+    <groupId>org.indunet</groupId>
+    <artifactId>fastproto-processor</artifactId>
+    <version>4.0.0</version>
+    <scope>provided</scope>
+</dependency>
+```
+
+**Gradle:**
+```groovy
+implementation 'org.indunet:fastproto:4.0.0'
+// Add if using lambda formulas
+annotationProcessor 'org.indunet:fastproto-processor:4.0.0'
+```
+
 ## [3.12.3] - 2025-11-23
 ### Added
 - New `@BcdType` annotation and `BcdCodec` for fixed-length packed BCD integers (with byte order support), mapped to `int` / `Integer`.

README-zh.md

@@ -45,14 +45,16 @@ FastProto 是一个面向 **二进制通信协议** 的高性能序列化 / 反
 <dependency>
     <groupId>org.indunet</groupId>
     <artifactId>fastproto</artifactId>
-    <version>3.12.3</version>
+    <version>4.0.0</version>
 </dependency>
-```
-
-* Gradle
 
-```gradle
-implementation "org.indunet:fastproto:3.12.3"
+<!-- 可选：使用 lambda 公式时需要 (@DecodingFormula(lambda="...")) -->
+<dependency>
+    <groupId>org.indunet</groupId>
+    <artifactId>fastproto-processor</artifactId>
+    <version>4.0.0</version>
+    <scope>provided</scope>
+</dependency>
 ```
 
 ## *1. 快速入门*
@@ -168,6 +170,8 @@ public class Weather {
 }
 ```
 
+> **注意:** Lambda 公式需要 `fastproto-processor` 模块，请将其添加为 `provided` 作用域的依赖。详见 [Android 指南](docs/android.md)。
+
 
 ## *2. 注解*
 
@@ -267,6 +271,17 @@ public class Weather {
 
 * *Lambda表达式*
 
+Lambda 公式由 FastProto 注解处理器（`fastproto-processor`）在编译时处理，这确保了与 Android 和 Java 11+ JRE 环境的兼容性。只需添加处理器依赖：
+
+```xml
+<dependency>
+    <groupId>org.indunet</groupId>
+    <artifactId>fastproto-processor</artifactId>
+    <version>4.0.0</version>
+    <scope>provided</scope>
+</dependency>
+```
+
 ```java
 import org.indunet.fastproto.annotation.DecodingFormula;
 import org.indunet.fastproto.annotation.EncodingFormula;

README.md

@@ -46,14 +46,16 @@ See the [CHANGELOG](CHANGELOG.md) for recent updates.
 <dependency>
     <groupId>org.indunet</groupId>
     <artifactId>fastproto</artifactId>
-    <version>3.12.3</version>
+    <version>4.0.0</version>
 </dependency>
-```
-
-* Gradle
 
-```gradle
-implementation "org.indunet:fastproto:3.12.3"
+<!-- Optional: For lambda formula support (@DecodingFormula(lambda="...")) -->
+<dependency>
+    <groupId>org.indunet</groupId>
+    <artifactId>fastproto-processor</artifactId>
+    <version>4.0.0</version>
+    <scope>provided</scope>
+</dependency>
 ```
 
 
@@ -169,6 +171,8 @@ public class Weather {
 }
 ```
 
+> **Note:** Lambda formulas require the `fastproto-processor` module. Add it as a `provided` scope dependency. See [Android guide](docs/android.md) for details.
+
 
 ## *2. Annotations*
 
@@ -272,6 +276,17 @@ complex formula, it is recommended to customize formula classes by implementing
 
 * *Lambda Expression*
 
+Lambda formulas are processed at compile time by the FastProto annotation processor (`fastproto-processor`). This ensures compatibility with Android and Java 11+ JRE environments. Simply add the processor dependency:
+
+```xml
+<dependency>
+    <groupId>org.indunet</groupId>
+    <artifactId>fastproto-processor</artifactId>
+    <version>4.0.0</version>
+    <scope>provided</scope>
+</dependency>
+```
+
 ```java
 import org.indunet.fastproto.annotation.DecodingFormula;
 import org.indunet.fastproto.annotation.EncodingFormula;

docs/android.md

@@ -1,54 +1,122 @@
 ## Android Compatibility Guide
 
-This page summarizes how to use FastProto on Android and current limitations.
+This page summarizes how to use FastProto on Android.
 
 ## What Works
 
 - Annotation-based mapping for primitive types, arrays, strings, enums, bit/byte order, and checksum/CRC
 - Decode/encode via `FastProto.decode(...)` and `FastProto.encode(...)`
 - Builder/Utils APIs (no annotations)
+- **Lambda formulas with annotation processor** (since 4.0.0)
+
+## Lambda Formulas on Android
+
+Since version 4.0.0, FastProto provides a separate annotation processor module (`fastproto-processor`) that generates formula classes at compile time. This makes `@DecodingFormula(lambda = "...")` and `@EncodingFormula(lambda = "...")` fully compatible with Android.
+
+### Setup
+
+**Gradle (Kotlin DSL)**:
+```kotlin
+dependencies {
+    implementation("org.indunet:fastproto:4.0.0")
+    annotationProcessor("org.indunet:fastproto-processor:4.0.0")
+}
+
+// For Kotlin projects, use kapt instead:
+// kapt("org.indunet:fastproto-processor:4.0.0")
+```
+
+**Gradle (Groovy DSL)**:
+```groovy
+dependencies {
+    implementation 'org.indunet:fastproto:4.0.0'
+    annotationProcessor 'org.indunet:fastproto-processor:4.0.0'
+}
+```
+
+**Maven**:
+```xml
+<dependencies>
+    <dependency>
+        <groupId>org.indunet</groupId>
+        <artifactId>fastproto</artifactId>
+        <version>4.0.0</version>
+    </dependency>
+    <dependency>
+        <groupId>org.indunet</groupId>
+        <artifactId>fastproto-processor</artifactId>
+        <version>4.0.0</version>
+        <scope>provided</scope>
+    </dependency>
+</dependencies>
+```
+
+### How It Works
+
+The annotation processor scans your code at compile time and generates `Function` implementation classes for each lambda expression. These generated classes are included in your APK and used at runtime instead of dynamic compilation.
+
+For example, this annotation:
+```java
+@Int16Type(offset = 0)
+@DecodingFormula(lambda = "x -> x * 0.1")
+private double temperature;
+```
+
+Generates a class like:
+```java
+public class YourClass_temperature_DecodingFormula implements Function<Integer, Object> {
+    @Override
+    public Object apply(Integer x) {
+        return x * 0.1;
+    }
+}
+```
+
+### Alternative: Custom Function Classes
+
+You can also use custom function classes directly without relying on the annotation processor:
+
+```java
+public class TemperatureFormula implements Function<Integer, Double> {
+    @Override
+    public Double apply(Integer value) {
+        return value * 0.1;
+    }
+}
+
+public class SensorData {
+    @Int16Type(offset = 0)
+    @DecodingFormula(TemperatureFormula.class)
+    private double temperature;
+}
+```
 
 ## Current Limitations
 
-- Dynamic formula compilation is unavailable on Android
-  - Reason: Android runtime does not ship `javax.tools.JavaCompiler`, nor support loading JVM `.class` via `URLClassLoader`/`defineClass`. Only DEX is supported at runtime.
-  - Impact: Using string-based lambda in `@DecodingFormula(lambda = "...")` / `@EncodingFormula(lambda = "...")` will fail on Android.
 - `java.sql.Timestamp` is not part of Android standard APIs
   - Impact: Types/codec relying on `java.sql.*` will not work. Prefer `long` epoch millis or `java.time.*` (with desugaring) instead.
 
-## How to Use on Android
+## Other Android Setup
 
-- Formulas
-  - Do NOT use string-based lambdas in annotations.
-  - Instead, implement `java.util.function.Function` (or a typed interface) as a normal class and reference the class in annotations.
-- Time Types
+- **Time Types**
   - Prefer `long` (epoch millis) or `java.time.Instant/LocalDateTime`.
   - Enable core library desugaring to use `java.time.*` on older Android.
-- Gradle Setup (library/app module)
+- **Gradle Setup (library/app module)**
   - compileOptions.sourceCompatibility/targetCompatibility = 1.8
   - coreLibraryDesugaringEnabled = true
   - Add dependency: `com.android.tools:desugar_jdk_libs`
-- R8/ProGuard
+- **R8/ProGuard**
   - Keep runtime annotations and members used by reflection
   - Example rules:
 
 ```pro
 -keepattributes RuntimeVisibleAnnotations, RuntimeVisibleParameterAnnotations, Signature, InnerClasses, EnclosingMethod
 -keep class org.indunet.fastproto.annotation.** { *; }
-# If you include the core jar and want to silence unused tools warnings:
--dontwarn javax.tools.**
--dontwarn java.net.URLClassLoader
+-keep class org.indunet.fastproto.formula.generated.** { *; }
 ```
 
-## Known Issues and Roadmap
-
-- Dynamic compiler will be made optional/disabled on Android to avoid `javax.tools` and custom classloader usage
-- Provide time codecs that do not depend on `java.sql.Timestamp` (prefer `Instant/long`)
-- Consider publishing an Android-friendly artifact variant
-
-These improvements are planned for future releases.
-
 ## FAQ
 
-- Can I still transform values? Yes. Implement a class-based function and refer to it in annotations, or transform in your own code before/after FastProto.
-- Do I need ProGuard rules? If you rely on reflection/annotations, keep them as shown above. If you do not use dynamic compilation, shrinkers will strip those classes automatically. 
+- **Can I use lambda formulas on Android?** Yes! Since 4.0.0, the `fastproto-processor` module generates formula classes at compile time, making lambda formulas fully compatible with Android.
+- **Do I need the annotation processor?** If you use `@DecodingFormula(lambda = "...")` or `@EncodingFormula(lambda = "...")`, yes. If you only use class-based formulas like `@DecodingFormula(MyFormula.class)`, the annotation processor is optional.
+- **Do I need ProGuard rules?** If you rely on reflection/annotations, keep them as shown above. The generated formula classes should also be kept.

docs/formulas.md

@@ -9,7 +9,7 @@ Formulas let you convert between raw on‑wire values and engineering values. Yo
 - Decode formula: raw -> target field type
 - Encode formula: target field type -> raw
 
-> Android note: avoid string-based lambdas in annotations; use class-based `Function` implementations instead. See `docs/android.md`.
+> **Note:** Lambda formulas require the `fastproto-processor` module for compile-time code generation. This ensures compatibility with Android and Java 11+ JRE environments. See [Android guide](android.md) for setup details.
 
 ## Quick Steps
 
@@ -28,10 +28,21 @@ Formulas let you convert between raw on‑wire values and engineering values. Yo
   - Example: reverse the above conversion.
 
 ### Lambda vs Class
-- Lambda: `@DecodingFormula(lambda = "...")` / `@EncodingFormula(lambda = "...")`
+- Lambda: `@DecodingFormula(lambda = "...")` / `@EncodingFormula(lambda = "...")` — requires `fastproto-processor` dependency
 - Class: `@DecodingFormula(MyFunc.class)` / `@EncodingFormula(MyFunc.class)` where class implements `Function<In, Out>`
 - Precedence: Class‑based formulas win if both lambda and class are present.
 
+### Lambda Processor Setup
+To use lambda expressions, add the annotation processor:
+```xml
+<dependency>
+    <groupId>org.indunet</groupId>
+    <artifactId>fastproto-processor</artifactId>
+    <version>4.0.0</version>
+    <scope>provided</scope>
+</dependency>
+```
+
 ### Lifecycle & Errors
 - Formulas are compiled/bound during graph resolve and invoked per field during decode/encode.
 - Throwing exceptions inside formulas will surface as `DecodingException` / `EncodingException` at call sites.