用 Quarkus quickjs4j 实现动态财务规则 —— 从入门到实践

在财务系统开发中，我们经常会遇到这样的难题：业务规则频繁变动，比如税率调整、费用计算方式变更等，每次变动都需要重新编码、测试和部署，不仅耗时费力，还可能影响系统稳定性。而 Quarkus quickjs4j 扩展的出现，为解决这一问题提供了全新的思路。它能让我们在 Quarkus 应用中无缝集成 JavaScript 代码，实现动态财务规则，无需重启应用就能更新逻辑。接下来，我将从财务开发的实际需求出发，详细介绍这个工具的使用。

财务系统为何需要 JavaScript 集成

财务系统的核心特点之一就是业务规则的易变性。一方面，国家的财务税收政策会根据经济发展情况进行调整，比如增值税率可能会有变动；另一方面，企业内部的财务制度也可能随着业务发展而改变，像费用报销标准、提成计算方式等。这就要求财务系统具备快速响应规则变化的能力。

JavaScript 作为一种动态脚本语言，在这种场景下有着明显的优势：

动态更新规则：当财务规则发生变化时，只需要修改对应的 JavaScript 脚本，无需重新编译和部署 Java 应用，大大缩短了规则更新的周期。

降低开发门槛：对于一些简单的财务规则调整，甚至可以由财务人员直接修改 JavaScript 脚本，减少了对开发人员的依赖。

复用现有资源：如果企业已经有一些用 JavaScript 编写的财务计算逻辑或算法，借助该扩展可以直接在 Java 财务系统中复用，避免重复开发。

快速验证规则：新的财务规则可以通过修改 JavaScript 脚本快速进行测试验证，便于及时发现和调整问题。

Quarkus quickjs4j 扩展则让 JavaScript 与 Java 的集成更加顺畅，同时还能保证系统的性能和安全性，非常适合财务系统的需求。

Quarkus quickjs4j 核心功能及财务场景适配

CDI 集成贴合财务开发习惯

对于 Java 开发者来说，CDI（上下文和依赖注入）是非常熟悉的技术。Quarkus quickjs4j 实现了与 CDI 的完整集成，让 JavaScript 脚本可以像普通的 Java Bean 一样被注入和使用。

在财务系统中，我们可以把各种财务计算逻辑封装成 JavaScript 脚本，然后定义对应的 Java 接口。通过 CDI 注入，在核心的财务服务中直接调用这些脚本实现的功能，就像使用普通的 Java 类一样自然。这种方式完全符合 Java 开发者的开发习惯，不需要学习新的编程模式，降低了使用门槛。

比如，我们可以定义一个费用计算的 Java 接口，用 JavaScript 实现不同类型费用的计算逻辑，然后在费用报销服务中注入该接口并调用，整个过程和使用 Java 实现的接口没有太大区别。

灵活的脚本加载满足多样财务需求

财务系统的规则来源多样，不同的规则有着不同的更新频率和使用场景。Quarkus quickjs4j 支持从多种来源加载 JavaScript 脚本，能够很好地满足这些需求：

类路径加载：对于那些相对固定、不需要频繁变动的财务规则，比如基本的会计核算公式，可以将对应的 JavaScript 脚本打包到应用的类路径中。这样在应用启动时就能加载这些脚本，保证规则的稳定性和可靠性。

文件系统加载：对于一些需要根据企业内部情况动态调整的规则，比如部门级的费用分摊规则，可以从文件系统加载脚本。当规则需要修改时，只需更新文件系统中的脚本文件，无需重启应用就能生效。

URL 加载：如果企业有统一的规则管理平台，财务系统可以通过 URL 从该平台加载最新的规则脚本，实现规则的集中管理和统一更新。比如从公司的财务政策服务器上拉取最新的税收优惠计算规则。

实战：动态增值税计算实现

下面以增值税计算为例，详细介绍如何在财务系统中使用 Quarkus quickjs4j。

步骤 1：添加依赖

首先，在项目的 pom.xml 文件中添加 Quarkus quickjs4j 扩展的依赖：

<dependency>

 <groupId>io.quarkiverse.quickjs4j</groupId>

 <artifactId>quarkus-quickjs4j</artifactId>

 <version>${quarkus-quickjs4j.version}</version>

</dependency>

同时，需要配置注解处理器，用于在编译时生成相关的代码：

<build>
 <plugins>

 <plugin>

 <groupId>org.apache.maven.plugins</groupId>

 <artifactId>maven-compiler-plugin</artifactId>

 <configuration>

 <annotationProcessorPaths>

 <path>

 <groupId>io.quarkiverse.quickjs4j</groupId>

 <artifactId>quarkus-quickjs4j</artifactId>

 <version>${quarkus-quickjs4j.version}</version>

 </path>

 </annotationProcessorPaths>

 </configuration>

 </plugin>

 </plugins>

</build>

步骤 2：定义增值税计算接口

创建一个 Java 接口，用于规范增值税计算的方法。这个接口将与后续的 JavaScript 脚本相对应。

import io.roastedroot.quickjs4j.annotations.ScriptInterface;

import io.quarkiverse.quickjs4j.annotations.ScriptImplementation;

import java.math.BigDecimal;

@ScriptInterface

@ScriptImplementation(location = "vat-calculator.js")

public interface VatCalculator {

 // 计算增值税额（含税金额、税率 -> 税额）

 BigDecimal calculateVatAmount(BigDecimal taxableAmount, BigDecimal taxRate);

 // 计算不含税金额（含税金额、税率 -> 不含税金额）

 BigDecimal calculateTaxExclusiveAmount(BigDecimal taxInclusiveAmount, BigDecimal taxRate);

}

步骤 3：编写 JavaScript 实现

在 src/main/resources 目录下创建 vat-calculator.js 文件，实现接口中定义的方法。

// 计算增值税额：含税金额 / (1 + 税率) * 税率
import jakarta.enterprise.context.ApplicationScoped;

function calculateVatAmount(taxableAmount, taxRate) {

 // 保留两位小数，符合财务计算精度要求

 return taxableAmount.divide(taxRate.add(new BigDecimal(1)), 2, RoundingMode.HALF_UP)

 .multiply(taxRate);

}

// 计算不含税金额：含税金额 / (1 + 税率)

function calculateTaxExclusiveAmount(taxInclusiveAmount, taxRate) {

 return taxInclusiveAmount.divide(taxRate.add(new BigDecimal(1)), 2, RoundingMode.HALF_UP);

}

export { calculateVatAmount, calculateTaxExclusiveAmount };

步骤 4：在财务服务中使用

在财务系统的核心服务中，通过 CDI 注入 VatCalculator 接口，并调用其方法进行增值税相关计算。

import jakarta.inject.Inject;

import java.math.BigDecimal;

@ApplicationScoped

public class FinancialVatService {

 @Inject

 VatCalculator vatCalculator;

 // 处理销售业务的增值税计算

 public VatCalculationResult calculateSalesVat(BigDecimal salesAmount) {

 // 假设当前增值税率为13%

 BigDecimal taxRate = new BigDecimal("0.13");

 // 计算增值税额

 BigDecimal vatAmount = vatCalculator.calculateVatAmount(salesAmount, taxRate);

 // 计算不含税金额

 BigDecimal taxExclusiveAmount = vatCalculator.calculateTaxExclusiveAmount(salesAmount, taxRate);

 return new VatCalculationResult(taxExclusiveAmount, vatAmount, taxRate);

 }

}

当税率发生变化时，比如国家调整增值税率为 11%，我们只需要修改调用时传入的 taxRate 参数即可；如果计算逻辑发生变化，只需修改 vat-calculator.js 文件，无需修改 Java 代码和重启应用，极大地提高了财务系统应对规则变化的灵活性。

进阶应用：复杂财务场景处理

多维度财务规则动态切换

在实际的财务工作中，可能需要根据不同的维度（如地区、客户类型、业务类型等）应用不同的财务规则。例如，不同地区的企业所得税优惠政策可能不同，我们可以利用 Quarkus quickjs4j 的动态脚本加载功能实现规则的动态切换。

import jakarta.enterprise.context.ApplicationScoped;

import jakarta.inject.Inject;

import java.io.IOException;

import java.nio.file.Files;

import java.nio.file.Paths;

@ApplicationScoped

public class MultiDimensionTaxRuleService {

 @Inject

 ScriptInterfaceFactory<TaxRuleCalculator, TaxRuleContext> taxRuleFactory;

 // 根据地区获取对应的企业所得税计算规则并计算

 public BigDecimal calculateEnterpriseIncomeTax(String region, BigDecimal profit) {

 // 根据地区确定脚本路径

 String scriptPath = "/financial/rules/enterprise-income-tax/" + region + ".js";

 try {

 // 读取脚本内容

 String scriptContent = Files.readString(Paths.get(scriptPath));

 // 创建计算器实例

 TaxRuleCalculator calculator = taxRuleFactory.create(scriptContent, new TaxRuleContext());

 // 计算企业所得税

 return calculator.calculate(profit);

 } catch (IOException e) {

 // 处理文件读取异常，如使用默认规则

 throw new RuntimeException("获取" + region + "企业所得税计算规则失败", e);

 }

 }

}

通过这种方式，当某个地区的企业所得税规则发生变化时，只需更新该地区对应的 JavaScript 脚本，系统就能自动应用新的规则，无需对整个应用进行改动。

财务规则执行日志与审计

财务工作对可追溯性要求极高，每一笔财务计算都需要有清晰的记录，以便后续审计和核对。我们可以利用 Quarkus quickjs4j 的上下文支持功能，实现财务规则执行过程的日志记录。

首先，定义一个日志上下文类：

import jakarta.enterprise.context.ApplicationScoped;
@ApplicationScoped

public class RuleExecutionLogContext {

 // 记录规则执行日志

 public void logExecution(String ruleName, String parameters, String result) {

 // 实际应用中可将日志存入数据库或日志文件

 System.out.println("Rule Execution - Name: " + ruleName + ", Parameters: " + parameters + ", Result: " + result);

 }

}

然后，在接口上关联该上下文：

@ScriptInterface(context = RuleExecutionLogContext.class)
@ScriptImplementation(location = "expense-reimbursement.js")

public interface ExpenseReimbursementCalculator {

 BigDecimal calculateReimbursementAmount(BigDecimal expenseAmount, String expenseType);

}

在 JavaScript 脚本中调用日志方法：

function calculateReimbursementAmount(expenseAmount, expenseType) {
 // 记录执行参数

 RuleExecutionLogContext_Builtins.logExecution("expense-reimbursement",

 "expenseAmount=" + expenseAmount + ",expenseType=" + expenseType, "calculating");

 // 不同费用类型的报销规则

 let reimbursementRate;

 if (expenseType === "travel") {

 reimbursementRate = new BigDecimal("0.9"); // 差旅费报销90%

 } else if (expenseType === "entertainment") {

 reimbursementRate = new BigDecimal("0.6"); // 业务招待费报销60%

 } else {

 reimbursementRate = new BigDecimal("1.0"); // 其他费用全额报销

 }

 let result = expenseAmount.multiply(reimbursementRate).setScale(2, RoundingMode.HALF_UP);

 // 记录执行结果

 RuleExecutionLogContext_Builtins.logExecution("expense-reimbursement",

 "expenseAmount=" + expenseAmount + ",expenseType=" + expenseType, result.toString());

 return result;

}

export { calculateReimbursementAmount };

这样，每次执行费用报销计算时，都会记录详细的日志，包括规则名称、输入参数和计算结果，满足了财务审计的需求。

财务系统使用该扩展的注意事项

确保财务计算精度

财务计算对精度要求极高，一点微小的误差都可能导致严重的问题。在使用过程中，要特别注意计算精度的控制：

避免使用 JavaScript 原生的 Number 类型进行财务计算，因为其可能存在精度丢失问题。应尽量使用 Java 的 BigDecimal 类型，并指定合适的小数位数和舍入模式。

在 JavaScript 脚本中进行计算时，严格按照财务计算规范处理精度问题，确保计算结果的准确性。

加强脚本版本管理

由于财务规则可能会频繁更新，为了避免规则混乱和便于追溯，需要加强对 JavaScript 脚本的版本管理：

为脚本文件添加版本标识，如在文件名中包含版本号，如 vat-calculator-v1.0.js、vat-calculator-v1.1.js 等。

建立脚本版本管理机制，记录每个版本的修改内容、修改时间和修改人等信息。

在加载脚本时，能够明确指定所需的版本，确保使用正确的规则。

做好性能优化

在财务系统中，可能会有大量的财务数据需要处理，对性能有一定的要求。可以从以下几个方面进行性能优化：

对于频繁调用的财务规则脚本，进行缓存处理，避免每次调用都重新加载和解析脚本，提高执行效率。

合理设计脚本逻辑，避免在脚本中进行复杂的循环和计算，尽量将耗时的操作放在 Java 代码中实现。

定期对脚本执行性能进行监控和分析，找出性能瓶颈并进行优化。

严格控制脚本权限

虽然沙箱机制提供了一定的安全保障，但还需要从源头控制脚本的权限：

明确脚本的上传和修改权限，只有经过授权的人员（如财务管理员）才能上传和修改脚本。

对上传的脚本进行严格的检查和审核，防止恶意脚本进入系统。

根据脚本的用途，最小化授予其资源访问权限，不随意开放不必要的权限。

总结

Quarkus quickjs4j 扩展为财务 Java 开发带来了全新的可能。它让 JavaScript 与 Java 的集成变得简单高效，使财务系统能够快速响应业务规则的变化，同时又能保证系统的安全性和性能。

通过在财务系统中应用该扩展，我们可以实现动态的财务规则管理，减少因规则变动带来的开发和部署成本，提高财务工作的效率。无论是简单的税率计算，还是复杂的多维度财务规则，都能得到很好的支持。

目前该扩展还处于实验阶段，但已经具备了核心的功能，非常值得在财务系统中进行尝试。随着后续版本的更新和完善，它在财务领域的应用前景将会更加广阔。

如果你也是财务 Java 开发者，不妨试试这个工具，相信它会给你的开发工作带来不少便利。如果在使用过程中有任何问题或建议，也可以参与到该项目的社区讨论中，为工具的完善贡献自己的力量。

相关资源：

Quarkus quickjs4j 官方博客

Quarkus quickjs4j GitHub 仓库

Menu

Share

用 Quarkus quickjs4j 实现动态财务规则 —— 从入门到实践

财务系统为何需要 JavaScript 集成

Quarkus quickjs4j 核心功能及财务场景适配

CDI 集成贴合财务开发习惯

灵活的脚本加载满足多样财务需求

实战：动态增值税计算实现

步骤 1：添加依赖

步骤 2：定义增值税计算接口

步骤 3：编写 JavaScript 实现

步骤 4：在财务服务中使用

进阶应用：复杂财务场景处理

多维度财务规则动态切换

财务规则执行日志与审计

财务系统使用该扩展的注意事项

确保财务计算精度

加强脚本版本管理

做好性能优化

严格控制脚本权限

总结

Comment

使用llama_index+通义千问实现一个简单AI程序

Ollama:在本地启动和运行大语言模型

干货总结-微服务治理之流量拆分

RAG 是什么

使用Java Record 实现DTO

SpringAI:使用Java编写GenAI应用程序

Testcontainers Database Integration Testing

干货总结-微服务治理之优雅停机

代码避坑：Check -DoSomething

2月27日随笔