分类：计算机 / 架构 / oa-backend-framework项目架构设计
- oa-backend-framework项目架构设计 - Web API
实现本地运行 OA系统遵循Java EE的JAX-RS规范来实现Web API，我们当然也必须遵循之。 JAX-RS本身只是一种规范，运行它还需要实现了这种规范的框架（通常为Jersey），以及Web容器（Jersey在Web容器上注册Servlet来接收请求）。OA系统使用的JAX-RS框架是Jersey，使用的Web容器是Resin。 要在本地运行Web API，只需要让我们的框架在本地具备（<scope>provided</scope>）JAX-RS规范（javax.ws.rs:javax.ws.rs-api）和Jersey框架（com.sun.jersey:jersey-bundle），并运行在本地的Web容器（Tomcat）中即可。 为了让Jersey能扫描到我们的控制器类，需要在web.xml中（本地和线上）修改<servlet-class>com.sun.jersey.spi.container.servlet.ServletContainer</servlet-class>的<param-value>值，将我们应用的包名附加到最后。 控制器类 JAX-RS使用@Path注解标记一个方法是一个资源（即一个API），使用@GET/@POST注解标记资源对应的HTTP方法，使用@QueryParam、@PathParam等注解获取请求中的参数，使用@Produces注解设置响应的内容类型（Content-Type）。@Path写在类上可表达公共路径前缀，@Produces写在类上可统一设置响应的内容类型。 可见，JAX-RS的基本使用跟Spring Boot的控制器是类似的，因此我们仍然称有@Path注解的类为控制器类，但它们的运行机制不太相同。在Spring Boot中，一个控制器类是一个Bean，全局只有一个实例。但在JAX-RS中，对于一个@Path类，每当一个HTTP请求映射到它时，它都会创建一个新的实例来执行。因此，我们的控制器类不能作为Bean管理。 为了简化控制器类的代码，我们编写所有控制器的抽象基类BaseController： // 所有API均返回JSON响应 @Produces(MediaType.APPLICATION_JSON) public abstract class BaseController { public BaseController() { // 注入依赖 IoCContainer.injectDependencies(this); } } 业务的控制器类继承自BaseController： public EntityController extends BaseController { @Resource private EntityService entityService; @GET @Path("/getEntity") public Entity get() { ... } } 自动数据库事务管理 我们希望执行一个API请求时，如果正常返回则自动提交数据库事务，如果发生异常则自动回滚数据库事务。 因为JAX-RS最终也是基于Servlet实现的，因此我们可以使用Servlet中的过滤器（Filter）机制，实现请求前、后的拦截，并在其中实现统一异常处理和自动数据库事务管理。 // 只拦截我们应用的API @WebFilter("/my/*") public class MyFilter implements Filter { @Override public void init(FilterConfig filterConfig) {} @Override public void destroy() {} @Override public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain) throws IOException, ServletException { try { // 当前请求线程获取数据库连接 ConnectionHolder.getConnection(); // 对于HTTP响应，做统一异常处理 if (response instanceof HttpServletResponse) { HttpServletResponse httpResponse = (HttpServletResponse) response; // HTTP响应包装器，重写方法，避免响应在其他Servlet或Filter中被提交导致无法修改响应体内容 HttpServletResponseWrapper httpResponseWrapper = new HttpServletResponseWrapper(httpResponse) { @Override public void sendError(int sc, String msg) {} @Override public void sendError(int sc) {} @Override public void sendRedirect(String location) {} }; try { // 执行 chain.doFilter(request, httpResponseWrapper); // 执行成功，提交数据库事务 ConnectionHolder.commit(); } // 捕获任何抛出，进行统一异常处理 catch (Throwable e) { // 回滚数据库事务 ConnectionHolder.rollback(); // 响应结果map Map<String, String> resultMap = new LinkedHashMap<>(); resultMap.put("error", e.getClass().getSimpleName()); resultMap.put("message", e.getMessage()); // 写入HTTP响应 httpResponse.setStatus(500); httpResponse.setContentType(MediaType.APPLICATION_JSON); httpResponse.getWriter().write(JSONUtil.toJsonStr(resultMap)); } } // 对于非HTTP响应，不做处理 else { chain.doFilter(request, response); } } finally { // 当前请求线程关闭数据库连接 ConnectionHolder.closeConnection(); } } }
- oa-backend-framework项目架构设计 - IoC容器
IoC容器+依赖注入大大降低了对象间依赖管理的复杂性，给Java开发带来了极大的便利。我们的应用同样遵循这个设计思想。 考察OA系统中可能可用的IoC容器，发现都不适合我们： Spring IoC容器：Spring的版本为1.2.6，有IoC容器功能，但由于版本过早，不支持注解。 OA系统自己的IoC容器com.weaverboot.frame.ioc.container.WeaIocContainer：与OA系统各机制强相关，无法确定是否能保证我们应用的隔离性，有互相影响的风险。 其实我们需要的特性很简单： 只需要支持单例。 只需要按类型注入。 基于注解的Bean类扫描和依赖注入。 因此，我们自己实现IoC容器。 Component注解：具有此注解的具体类（非抽象类）将会作为Bean管理。 IoCContainer类： 使用Map<Class<?>, Object> beanMap保存每个类对应的Bean实例。 使用Hutool（在OA系统的三方库中）的ClassScanner扫描应用的包，对每个带有@Component注解的具体类，调用registerBean()注册Bean实例。 registerBean(Class<?> clazz)方法：先检查clazz在beanMap中是否存在，存在则不重复注册。不存在，则调用clazz的无参构造器创建Bean实例，并保存到beanMap中，然后调用injectDependencies()注入依赖。注意：这里要先保存到beanMap，再注入依赖，否则在循环依赖、自身依赖的场景下会无限递归。 injectDependencies(Object object)方法：遍历object所在类及所有祖先类的实例属性，如果属性有@Resource注解，且属性值为null，则按属性的类型获取Bean实例，并设置为属性值。如果该类型对应的Bean实例不存在，则先调用registerBean()注册之。 应用启动时，会调用IoCContainer扫描、注册Bean实例，并注入依赖，完成IoC容器的初始化。
- oa-backend-framework项目架构设计 - 数据库层
OA系统使用weaver.conn.RecordSet类和weaver.conn.RecordSetTrans类来执行数据库操作，其中RecordSet不支持事务，RecordSetTrans支持事务。这两个类的代码量非常大，在没有文档和注释的情况下，仅通过逆向分析，我们根本无法保证能正确地使用其特性。因此，为了更加可控，我们自己实现数据库层。 数据源管理器 DataSourceManager类负责初始化数据源，并从数据源获取数据库连接。启动应用时，会调用DataSourceManager执行初始化。 初始化数据源：我们使用Druid（在OA系统的三方库中）作为数据库连接池。读取OA系统的数据源配置文件weaver.properties，用其中的配置创建DruidDataSource实例，并保存在DataSourceManager的静态属性中。 获取数据库连接：从DruidDataSource实例上获取数据库连接。 线程的数据库连接 ConnectionHolder类是一个ThreadLocal容器，用于保存当前线程的数据库连接，确保一条线程的所有操作都在同一个连接中，即在同一个事务中。 ConnectionHolder提供获取连接、关闭连接、提交事务、回滚事务这4个方法。 数据库服务 应用没有专门的DAO层框架，直接用JDBC模式操作数据库又很繁琐，因此，我们以服务的形式提供通用的数据库操作功能。 DatabaseService类是通用的数据库服务类，封装了通用的查库和写库操作的方法。此服务可以通过IoC容器注入到其他类中，应用中所有的数据库操作最终都是通过调用DatabaseService来完成。 DatabaseService使用Apache Commons DBUtils（在OA系统的三方库中）的QueryRunner来执行SQL。执行时，总是从ConnectionHolder获取数据库连接。 DatabaseService类提供以下查库方法： 方法 描述 查询结果为0行 查询结果为1行 查询结果为多行 queryRowOrNull 获取唯一行 返回null 返回唯一行 抛出异常 queryRow 获取唯一行 抛出异常 返回唯一行 抛出异常 queryFirstRowOrNull 获取第一行 返回null 返回第一行 抛出异常 queryFirstRow 获取第一行 抛出异常 返回第一行 抛出异常 queryRows 获取行列表 返回行列表（空） 返回行列表（1行） 返回行列表（多行） DatabaseService类提供以下写库方法： insert：插入 update：更新 delete：删除 所有查库和写库方法都支持参数String sql, Object... params，防止注入攻击。 通用的行数据结构 为了通用地表示DatabaseService查库方法查询到的任意结构的行数据，我们定义了Row类。 Row类是一个Map，类似于JavaScript的对象、Python的字典，可以表示任意的数据库行、实体、对象等数据结构。用Map表示对象，可以无需对属性做预定义，可以按需自由地增删属性，这带来了一些灵活性（例如：可以构造更新部分字段的更新数据对象，可以将一种对象修改为另一种对象，可以在字段增减时热更新程序），也降低了一些确定性（例如：IDE因为不知道有哪些属性而无法做代码提示和检查错误）。 Row类继承自LinkedHashMap<String, String>。考虑实际使用场景，我们对其做了一些约束。 键，即对象的属性名，是大小写无关的。通过重写Map的get()、put()等方法，统一将键转换为小写形式，来实现大小写无关性。 值，即对象的属性值，存储为字符串。通过重写Map的put()等方法，实现无论给的值是何种类型，都统一转换为字符串存储，其中null会存储为空字符串。通过增加getInt()、getBigDecimal()等方法，提供获取合适数据类型的功能。这种设计，屏蔽了数据类型的不确定性（例如：小数是Double还是BigDecimal），也使其不支持嵌套的对象。 对于Map具有的、但对对象来说意义不大的方法，如compute()，我们重写之并直接抛异常，以阻止其被使用。 应用中的各种业务数据类都继承自Row，或者直接使用Row。DatabaseService的查库方法支持泛型，可以返回指定的业务数据类（Row或Row的子类）。
- oa-backend-framework项目架构设计 - 启动应用
OA系统的启动原理：OA系统在Web容器上注册了一个Servletweaver.general.InitServer。启动Web容器时，会执行InitServer的init()方法，OA系统就在该方法中启动，执行各种初始化操作。 同理，我们也可以在Web容器中注册一个ServletMyApplicationStartupServlet，实现启动： // 使用@WebServlet注解注册Servlet，可以免于修改web.xml。 // loadOnStartup：取最大整数，确保应用在OA系统启动之后才启动。 // urlPatterns：此Servlet不处理HTTP请求，但注解要求必填，所以这里给一个不会与OA系统冲突的路径即可。 @WebServlet(loadOnStartup = Integer.MAX_VALUE, urlPatterns = "/my") public class MyApplicationStartupServlet extends HttpServlet { @Override public void init() { // 启动应用程序，执行初始化 } } 应用启动时执行的初始化过程： 打印应用logo，类似于Spring Boot，这可以让我们在日志中更显著地看到应用启动。 初始化数据源。 初始化IoC容器。 对OA系统进行配置，例如动态注册免用户身份检查的API路径前缀（unchecksessionurl）。
- oa-backend-framework项目架构设计 - 总体架构
总体思路上，我们要做一个相对独立的后端应用程序。 这个应用具有独立的分层设计，主要分层如下： 业务请求入口： 控制器层：接收来自Web API的业务请求。控制器类会注册到Web容器中。虽然API主要都写在我们的Spring Boot项目中，而不是写在这里（因为很麻烦），但仍然有部分涉及OA系统的API必须写在这里。 流程动作层：接收来自OA系统的执行流程动作的业务请求。流程动作类会注册到OA系统中。 服务层：实现业务服务，是业务逻辑的核心。 数据库层：实现对数据库的读写，支持事务管理。 应用与OA系统运行在同一个JVM中，可以在代码层面与OA系统进行交互。 应用将实现一个开发框架，这个开发框架将做到： 本地运行，方便调试：所有与OA系统非强相关的业务代码，都支持在本地运行，可以在Web容器上运行API，可以通过JUnit运行流程动作。本地运行时，可以方便地通过IDE断点做调试。 打包部署：整个项目可以打成一个jar包，然后整体上传、部署到OA系统中，方便更新和版本控制。 良好封装：框架对与OA系统的交互做良好封装，业务代码完全透明，或只需使用封装后的简单概念和接口，无需自己处理OA系统的复杂细节。 事务控制：一个业务请求（API或流程动作）的所有代码都运行在一个数据库事务中，支持自动提交和回滚。 开发规范：制定合理的开发规范，包括包结构、实体划分、服务粒度等，使业务代码更清晰有序、更可复用、更可维护。 由于本质上仍然是嵌入到OA系统中运行，应用面临如下限制： 部署后仍然要重启OA：必须重启JVM，才能使新代码生效。 三方库有限：应用只能使用OA系统自带的三方库，且必须同版本。为了避免影响OA系统，不允许向OA系统中加入其他三方库或已有三方库的其他版本。
- oa-backend-framework项目架构设计 - 起步
我们的OA系统是泛微的Ecology 9。OA在走流程审批时，经常需要在到达或离开某个流程节点时，将流程中的数据保存到某个位置，或执行其他的业务操作。如果操作很复杂，就需要用代码来实现。OA提供了机制，让我们能写Java代码，部署到OA系统中，然后在流程的指定时机，调用我们的代码。 泛微给了我们这样一个开发框架：一个Java项目，依赖Maven库com.github.liuzhenghui:weaver-ecology-core:9.00.2102.17，这个库提供了Ecology 9的类结构，能编译，但不能本地运行。这个项目主要用来写流程动作和Web API。我们需要按规定在本地写好Java类，编译成class文件，上传到OA服务器中的指定目录，重启OA，然后执行它进行测试。如果要修改，则必须重复上述过程。 这个开发框架存在以下主要问题： 调试困难：不能本地运行，只能在服务器上运行，调试只能靠打印日志。 部署困难：只能逐个上传class文件，不能打包部署。多人、长期各自上传，使得class文件的版本难以控制。更新class文件后，要重启OA才能生效，重启时间很长。这种模式，使得我们不敢多写类，大量的代码挤在一个类中。 缺少封装：业务代码必须直面OA的底层机制，必须手动处理OA的元数据、权限等机制细节，缺少机制文档的情况下很容易出错。每个业务都要重复做这样的处理。 缺少事务控制：多个步骤中间出错时，会导致数据不一致。 缺少开发规范：只提供了与OA交互的基础机制，没有给出合理的程序结构，使得业务代码的组织相当混乱。 近期，我被调入公司新成立的信息部门，负责整个公司内部信息化的技术工作。同时，一个中等规模的独立业务系统需求被提到我们部门，与OA系统强相关。因此，我决定从这里入手，正式开始着手解决已经越来越明显的软件架构问题。 我将发起一个新的软件项目oa-backend-framework，从零开始对其进行架构设计，解决上述问题，积累架构经验，并用这个需求进行实战检验。 为什么不在上述开发框架上修改？已经尝试过了，但该框架与我的设计相差很大，修改势必带来很多冲突，导致两头都做不好。 OA系统本身就有成熟的架构和规范，为什么不遵循之？① 该架构是面向OA系统本身的问题域的，与我们的问题域并不相同；② 我们缺乏足够的文档信息和支持，对其架构和规范知之甚少；③ 基于已经了解到的信息，我们认为，即使遵循之，也无法完全解决上述问题，反而会带来新的麻烦。