简介：Axelor Open Platform是一款面向企业级业务应用开发的开源Java框架，基于JPA、JSF等Java EE标准，适合熟悉Java生态的前后端开发者快速构建可扩展、可定制的业务系统。框架兼顾前端JavaScript交互，从数据库管理到用户界面均提供统一方案，覆盖数据模型、服务编写、视图构建与数据交互等开发链路；资源包内含快速入门指南，通常涵盖环境安装、配置及首个示例应用运行，也配有API参考、教程、最佳实践与FAQ等详细文档，便于新手迈过环境门槛，团队也能按项目自由定制。压缩包为zip格式，大小6.53MB，文件统计暂未提供；包内代码以master主分支形式提供，通常对应框架最新稳定版本。当前已有505人学习浏览，适合需要中后台系统快速成型或进行Java框架选型参考的开发者。借助这套开源框架，可在获得源代码的前提下调整底层逻辑，降低企业级应用从原型到交付的重复开发成本，提升整体工程效率。
1. 当「改一个字段要动五层代码」成为常态，Axelor Open Platform 就是那一剂后悔药
业务应用程序开发的最大痛点从来不是写不出代码，而是改不动代码。某公司一个客户档案模块，甲方在验收前半个月提了个需求：给客户加一个「信用等级」下拉框。结果前端表单要改，后端 DTO 要加字段，数据库要加列，导入导出要同步，权限还要单独配置。五处改动，三个开发各忙半天，还差点把生产库的表结构弄出事故。我接手后把系统迁到了 Axelor Open Platform，这类需求从提测到上线基本控制在半小时内。Axelor Open Platform 是一个用于业务应用程序开发的开源 Java 框架，它的核心思路是模型驱动：你把业务对象定义成 Java 实体类，页面、数据库表、菜单、权限、工作流全部从这个模型自动生成。适合那些想保留 Java 代码掌控力，又不想在脚手架和重复 CRUD 上耗死的团队。
2. 模型驱动不是口号，是编译期的约定：Axelor Open Platform 的技术底座
2.1 模型驱动的本质：Java 实体类就是数据库表、表单、列表的数据源
Axelor Open Platform 把「业务对象」作为一切开发的起点。你在一个模块里写一个普通的 JPA 实体类，该实体类不仅映射数据库表，还自动成为后续视图、菜单、权限、导入模板的元数据来源。这和我之前用 Spring Boot 写接口的思路差别很大：传统写法里实体、DTO、VO 各管一摊，而这里一个模型贯穿始终。
package com.example.sales; import javax.persistence.Column; import javax.persistence.Entity; import javax.persistence.EnumType; import javax.persistence.Enumerated; import com.axelor.db.Model; @Entity public class Customer extends Model { @Column(nullable = false, length = 64) private String name; @Column(length = 32, unique = true) private String customerNo; @Enumerated(EnumType.STRING) private CreditLevel creditLevel; private Boolean active = Boolean.TRUE; public String getName() { return name; } public void setName(String name) { this.name = name; } // 其余 getter/setter 省略，IDE 可自动生成 }这段代码的逻辑要点是：继承框架提供的Model基类，你立刻拥有id、version、createdOn、updatedBy等公共字段，不需要自己维护审计列。@Column(nullable = false, length = 64)会同时影响数据库建表和页面表单校验；@Column(unique = true)会在数据库层生成唯一约束。写完后运行模块安装任务，框架会自动在数据库里建表，并在管理后台注册这个模型。
参数说明：length是数据库 varchar 长度，也是界面输入框的最大长度；CreditLevel用枚举类型存储字符串值，避免后端再转码。字段一般建议显式设置length，否则默认值可能偏长或偏短，后续再想改长度就得走迁移。
2.2 为什么选它而不选纯低代码平台：四个内置模块的边界
市面上低代码平台很多，但多数把业务逻辑藏在一个黑匣子里，出了问题没法下断点。Axelor Open Platform 选择了一条折中路线：模型由代码定义，界面由 XML 描述，逻辑用 Java 编写，整个应用最终打成一个标准 WAR 包放到 Tomcat 里跑。
| 内置模块 | 职责范围 | 落地时最常用的功能 |
|---|---|---|
| Meta 元数据模块 | 管理模型定义、视图定义、菜单定义 | 通过数据库记录所有业务对象的字段与界面配置，支持在线查看模型清单 |
| BPM 流程模块 | 定义状态机、审批流、自动化节点 | 把「信用审批」「请假申请」这类流程规则化，配置成 XML 而不是写死在 Service 里 |
| Security 权限模块 | 用户、角色、对象级权限、字段级权限 | 基于角色的菜单可见性、记录级过滤、按钮级授权 |
| Reporting 报表模块 | 模板生成与打印 | 做单据打印、导出 Excel、统计报表 |
实际开发中我一般这样划分：Meta 负责「这个业务对象长什么样」，BPM 负责「这个对象的状态怎么流转」，Security 负责「谁能看、谁能改」，Reporting 负责「怎么打印出来」。这种做法比单独拿 Activiti、Shiro、JasperReports 拼装少了好几层适配工作。
2.3 第一次启动：从源码构建到跑起来的最小动作
拿到框架源码后，不要急着在 IDE 里打开几万个文件。先确认环境，然后走一遍构建流程。我一般用 Maven 方式跑，数据库分开准备。
export JAVA_HOME=/path/to/jdk export MAVEN_HOME=/path/to/maven # 先建数据库，Axelor Open Platform 推荐使用 PostgreSQL createdb -U postgres axelor_demo # 构建整个发布包，跳过测试以加快首跑 mvn clean package -DskipTests # 将生成的 war 包部署到 Tomcat 的 webapps 目录 cp webapp/target/*.war $TOMCAT_HOME/webapps/ROOT.war # 启动 Tomcat，日志输出到 catalina.out $TOMCAT_HOME/bin/startup.sh参数说明：-DskipTests跳过单测，首次构建能节省不少时间，但交付前必须回归；webapp/target/*.war中的webapp是常见的聚合模块名，如果你的工程结构不同，请以你本地的 Maven 模块列表为准；把 WAR 命名为ROOT.war是为了让实例直接以根路径访问，省去上下文路径带来的菜单 URL 维护成本。
启动之后打开管理后台，如果能看到模型管理页面里列出了你新建的Customer实体，说明模型驱动链路已经打通。如果列表是空的，先回头查数据源配置是否正确，这是最常见的首跑翻车点。
3. 从建表到界面可用：用一份业务对象加两份 XML 做出可提交的改动单
3.1 先定义模型，再让它长出界面：Customer 的完整落地
讲了原理，接下来做一个真正能提交给测试的业务功能。需求很简单：客户主数据维护，要求客户编号唯一、信用等级必填、列表按创建时间倒序。先保证模型字段和校验正确，再处理界面。
package com.example.sales; import java.math.BigDecimal; import javax.persistence.Column; import javax.persistence.Entity; import javax.persistence.EnumType; import javax.persistence.Enumerated; import javax.persistence.Transient; import com.axelor.db.Model; @Entity public class Customer extends Model { @Column(nullable = false, length = 64) private String name; @Column(length = 32, unique = true) private String customerNo; @Enumerated(EnumType.STRING) private CreditLevel creditLevel; @Column(precision = 10, scale = 2) private BigDecimal creditLimit; private String remark; @Transient private String displayName; public String getDisplayName() { return customerNo + " - " + name; } }逻辑说明：creditLimit用BigDecimal而不是double，因为金额字段在报表和审批里出现精度问题很难排查；@Transient标注的displayName不会建列，它只是给列表视图拼一个可读名字。这样设计之后，列表页可以直接显示「C001 - 某某公司」，而不用在前端再写拼接逻辑。
参数说明：precision = 10, scale = 2表示最多十位数字、两位小数，适合绝大多数人民币金额场景；unique = true生成数据库唯一约束，同时框架会在前台校验重复值。实践里常见误用是把唯一约束写进 Service 手工判断，其实数据库约束才是兜底的防线。
3.2 视图 XML：让界面生成的顺序与校验规则可控
模型定义好之后，界面不会自动变得好看，但框架能根据模型字段生成一个默认表单。默认表单的问题是按字段声明顺序排列，且没有分组。我们需要一份视图配置来控制布局。
<?xml version="1.0" encoding="UTF-8"?> <view name="customer-form" title="客户档案" model="com.example.sales.Customer"> <field name="name" title="客户名称" required="true"/> <field name="customerNo" title="客户编号" required="true" readonly="true"/> <field name="creditLevel" title="信用等级" required="true"/> <field name="creditLimit" title="信用额度" widget="BigDecimal"/> <field name="remark" title="备注" widget="TextArea"/> </view>这段 XML 的作用是覆盖默认界面：required="true"会在表单提交时做非空校验；readonly="true"表示该字段不允许手动输入，适合由后台流水号生成器填充的编号；widget属性决定呈现方式，金额用数字输入框，多行备注用文本域。写完这份文件后，在模块注册表里声明视图文件路径，菜单里挂一个指向该视图的入口，刷新页面就能看到表单。
参数说明：view标签上的model必须与实体全限定类名一致，这是新手容易写错的地方；field的name必须与实体属性名对应，框架不会在界面上替你纠错，写错只会得到空白页。
3.3 部署细节：构建参数与 Tomcat 版本的红线
构建时有一个参数经常被忽略：字节码版本。如果你本机用新版本 JDK 编译，而公司的 Tomcat 运行环境还在用旧版本，启动时会直接报UnsupportedClassVersionError。
mvn clean package -DskipTests -Dmaven.compiler.source=1.8 -Dmaven.compiler.target=1.8逻辑说明：maven.compiler.source和target指定编译产物的字节码版本。运行时环境的 Tomcat 决定你该编译成什么版本，不是本机装了哪个 JDK 就用哪个。常见做法是统一用长期支持版 JDK 开发，编译目标锁定到运行环境兼容的最低版本。团队里如果有人改了这两个参数，代码经常出现「我本机能跑，上了测试环境就崩」的情况。
部署时还要注意：Axelor Open Platform 的运行时依赖 Tomcat 的标准类加载机制，不允许把第三方库随意塞进lib目录。war 包内已经捆绑了各模块的依赖，如果你在 Tomcat 的lib下额外放置一份同名 jar，classpath 冲突会引发诡异行为，比如视图加载一半丢失、接口偶发超时。遇到这种情况，先清理多余 jar，再考虑其他排查方向。
4. 把流程塞进框架：审批流与动态角色是 Axelor Open Platform 的护城河
4.1 从「请一次假」到「客户信用审批」：流程配置怎么写
业务系统里真正复杂的不是增删改查，而是状态流转。Axelor Open Platform 的 BPM 让我省掉了大量手写状态机代码。以客户信用额度审批为例，需求是：销售录入一个超过默认额度的客户，经理审批，通过后自动生效。传统做法是在 Service 里写一堆if (status == 1)判断，流程一变就要改代码。这里把流程抽成独立的流程定义。
<?xml version="1.0" encoding="UTF-8"?> <process name="customerCreditApproval" version="1"> <node name="start" type="Start"/> <node name="salesSubmit" type="Task" assignee="role:sales"/> <node name="managerApprove" type="Approval" assignee="role:manager"/> <node name="end" type="End"/> <transition from="start" to="salesSubmit"/> <transition from="salesSubmit" to="managerApprove" condition="creditLimit > 50000"/> <transition from="managerApprove" to="end" result="approved"/> <transition from="managerApprove" to="salesSubmit" result="rejected"/> </process>逻辑说明：assignee决定任务分给谁，role:sales表示分给所有拥有销售角色的用户；流转条件creditLimit > 50000会在每次离开节点时求值；result="approved"和result="rejected"是审批节点的输出路径。当审批人点了「同意」，流程走向end；点了「驳回」，任务回到销售重新处理。
参数说明：条件表达式里引用的creditLimit是当前流程关联的业务对象字段，框架会在运行时解析。流程启动时要把业务对象关联进流程上下文，否则条件解析会报空指针。这个配置的价值在于：你改变审批层级时只改 XML，不碰 Java 代码，测试成本大幅降低。
4.2 动态审批人：为什么不用把用户名写死在 XML 里
实际业务里审批人经常变化：经理换人了，部门调整了，职位名称变了。如果把具体用户名写进流程文件，每次人事变动都要改配置重启。解决方法是用动态求值表达式。
assignee="el:com.example.sales.RoutingRules.getCreditManager(customer)"逻辑说明：el:前缀表示该表达式由规则引擎动态求值。这里调用了一个静态 Java 方法，传入当前客户对象，方法内部查数据库找到该客户所属区域的销售经理。静态方法返回用户的登录名，框架自动把任务分配给这个人。这样一来，人事变了改数据库关联即可，流程定义不用动。
使用el:表达式时要注意两点：方法必须可静态访问，不能依赖未初始化的实例状态；方法执行频率取决于节点流转次数，不要在方法里做批量查询，如果逻辑较重，内部加一层缓存。某开发团队曾把整个客户列表查出来再遍历找经理，结果审批列表加载慢了三秒，就是没注意这个执行频率。
4.3 流程触发与业务代码解耦：事件监听器比 Service 调用更优雅
流程定义好了，怎么启动？常见误用是直接在 Service 方法里调用流程 API，然后把业务逻辑也塞进 Service，最后流程和业务代码缠在一起无法单测。我一般用事件监听器：业务对象的状态变化触发事件，事件监听器决定是否启动流程。
package com.example.sales.event; import com.axelor.event.Observes; import com.example.sales.Customer; public class CustomerEventHandler { void onCustomerCreated(@Observes Customer customer) { if (customer.getCreditLimit() != null && customer.getCreditLimit().compareTo(new BigDecimal("50000")) > 0) { // 启动信用审批流程，代码省略实际调用 startApproval(customer); } } }逻辑说明：@Observes是事件订阅的注解，Customer对象被创建并提交后，框架会广播该事件，当前监听器被调用。信用额度超过阈值才启动审批，没超过就直接跳过流程。这个模式的好处是：流程启动条件写在监听器里，业务模型层完全不知道有审批这件事，新增触发条件时不需要改动现有 Service。
参数说明：监听器方法名可以随意，但参数类型必须是订阅的事件类型。如果事件类型写错，编译期不会报错，运行时也不执行，这类问题还比较难发现——排查时可以看看启动日志里有没有「observer」相关的注册信息。
5. 避坑指南：Axelor Open Platform 落地中的六个高频事故
5.1 改字段后重启报「列不存在」
现象：给实体加了字段，运行模块安装任务提示成功，但一访问页面就报错，错误信息里说某个列在数据库里不存在。
原因：框架根据模型定义创建表，但对已存在的表只做有限的结构同步。部分新增列不会自动补上，尤其是加了非空约束的字段，数据库迁移策略选了保守模式。
解决：不要直接手工改实体类里的字段来救急。连接数据库，手动补齐缺失的列，再重启。也可以把改动写进模块的升级 SQL 脚本，由安装流程统一执行。需要注意，手工补列必须与实体字段的注解保持一致，比如长度、精度、是否非空。
5.2 视图配置了字段但页面是空白
现象：在视图 XML 里加了字段，菜单也能打开，但页面上该区域是空白，控制台也不报错。
原因：字段名与实体属性名不一致，或者model属性写错了全限定类名。框架对这类配置错误偏向于静默处理，只在日志里打一条警告。
解决：先查日志里的警告信息，再逐个核对view的model属性与field的name。如果还是空白，把视图 XML 临时精简到只剩一两个字段，通过二分法定位是哪行配置出错。不要试图一次配置十几个字段再统一排查。
5.3 审批人收到的是旧角色的用户
现象：人员调动之后，新审批人没收到任务，旧审批人还能看到待办。
原因：流程节点在任务创建时求值了审批人，并把结果写入流程上下文。人员角色变化不会触发重新求值，已经处于待办状态的任务仍然指向旧审批人。
解决：在流程节点上配置重新求值策略，让任务每次显示前计算有效审批人。如果框架版本不支持该配置，就在节点前置一个服务任务，刷新流程上下文中的审批人变量。不要指望修改角色后所有历史待办自动清洗，这是流程引擎的通用行为。
5.4 接口调用返回 403 权限错误
现象：从外部系统调用 REST 接口，有些接口能通，有些直接 403，浏览器里访问却正常。
原因：安全过滤器对非界面请求走的是另一套鉴权链路，匿名用户的权限集里没有这些接口的调用权，或者调用方缺少必要的角色令牌。
解决：检查接口定义里的权限声明，给对应的角色补充调用权。排查时先确认调用来源是服务到服务的内部认证还是普通用户会话，两种场景的配置入口不一样。403 和 401 要区分开，401 是没认证，403 是没授权，原因和修法完全不同。
5.5 中文乱码集中出现在导出 Excel 和打印 PDF
现象：界面显示中文正常，但导出的 Excel 和打印的 PDF 里中文变成问号或方块。
原因：模板文件的编码与运行时读取编码不一致，或者模板中文字体缺失、字体配置错误。企业环境里这类问题最常见于字体缺失，而不是数据库字符集问题。
解决：先确认导出模板文件的编码是 UTF-8，再确认运行环境里安装了中文字体。如果是缺失，为运行环境补装字体后重启应用。处理时还需要看看是否需要在 Tomcat 启动脚本里显式指定文件编码参数，这要结合运行环境决定，不要一上来就怀疑数据源。
5.6 列表查询慢，越用越卡
现象：本地开发环境一切正常，生产环境列表数据量过万后查询明显变慢，加索引也没太大改善。
原因：列表页默认查询可能带了权限过滤和动态属性计算，每行都要执行额外的数据访问。数据量大了以后，这些行级处理叠加导致响应时间上升。
解决：查看列表视图配置，去掉不必要的compute表达式和跨表字段；把常用的过滤条件固化成索引；如果权限过滤是逐行解析的，考虑改用记录级权限的批量匹配机制。我给一个比较务实的建议：先关掉列表里的所有计算字段，性能通常立刻恢复，再逐个加回来评估代价。
6. 进阶：用自定义事件做跨模块解耦，让审批流自己驱动后续业务
到了这个阶段，你已经能建模型、配视图、跑流程、查权限。最后一个建议是把「状态变化后的动作」从流程配置里挪到事件监听器里。之前在某公司做一个销售订单模块，审批通过后要同时做三件事：生成出入库单、更新客户信用占用额度、给财务发一条待办消息。最初我把这些逻辑全写进流程节点脚本，结果业务调整时脚本改了半个月，测试还老漏。后来我改成事件驱动，代码简洁了很多，问题也好定位了。
package com.example.sales.event; import javax.inject.Inject; import com.axelor.event.Event; import com.axelor.event.Observes; import com.example.sales.SaleOrder; public class SaleOrderEventListener { @Inject private Event<SaleOrderApproved> approvedEvent; void onApproval(@Observes SaleOrder order) { if ("approved".equals(order.getStatus())) { approvedEvent.post(new SaleOrderApproved(order)); } } }这段代码演示的是：流程把订单状态置为approved后，监听器捕获这个变化，再触发一个业务级事件SaleOrderApproved。库存模块、财务模块各自监听这个业务事件，执行自己的逻辑。三个模块之间没有直接引用，谁都改不动谁，也不会因为一处逻辑报错把其他模块拖垮。
参数说明：Event<T>是事件发布器，post方法同步推送事件；如果需要异步处理，把事件方法标注成异步即可，但要做好异常兜底。这个模式最大的收获不是性能，而是模块边界清晰了——你给团队画了一张图，哪个模块消费什么事件，一眼就能看懂。
最后讲一个我自己的教训：别在流程 XML 里写复杂的业务运算。流程文件适合描述「谁审批、审批后去哪」，不适合描述「审批后如何计算」。曾经我试图在流程里写一段脚本算税额，结果维护的人完全懵了，最后不得不重构成事件监听器。现在我对团队的约定是：流程只做路由，业务动作一律走事件。这样每段逻辑都可以单独写单元测试，问题一抛出就知道是谁的责任。希望这些做法对你有所帮助，在 Axelor Open Platform 上少走几个月的弯路。
本文还有配套的精品资源，点击获取
