hsweb-framework: a reactive Spring Boot 2 backend foundation, used as Maven modules

What hsweb-framework solves, and for whom

Most admin backends in Java start the same way: a Spring Boot skeleton, a permission table, a query builder, a cache layer, and a few months of glue code. hsweb-framework packages that glue. The README describes it as an enterprise backend management base project built on spring-boot 2.x, and it says it is the first to use fully reactive programming in that role. The stated use cases are open source admin systems, modular admin systems, systems whose features are meant to be extended, systems that integrate common functions, and front-end and back-end separated systems. The audience is narrower than that list suggests. The README warns that before using hsweb you should already have some understanding of project-reactor and spring-boot. This is not a framework you can pick up while learning Reactor. It is a framework you adopt after you are comfortable with Mono, Flux and the WebFlux request model, because its CRUD layer, its transaction control and its permission checks all return reactive types.

The reactive CRUD and permission mechanism

The architecture is a set of Maven modules rather than one artifact. The README lists hsweb-core for framework basics and utility classes, hsweb-commons for general shared functions, hsweb-datasource, hsweb-concurrent for concurrency and caching, hsweb-logging, hsweb-authorization for permission control, hsweb-starter as the module starter, and hsweb-system for common system functions. The data path runs through R2DBC and hsweb easy orm, which the README describes as an ORM wrapper over R2DBC. The supported databases listed are H2, Mysql, SqlServer and PostgreSQL. Two mechanisms stand out. The first is a DSL-style query and update builder. The README shows createQuery().where("name",name).fetch() producing a where clause, and createUpdate().set(user::getName).where(user::getId).execute() producing an update. The README claims this lets the front end pass parameters directly without worrying about SQL injection, which is a design claim worth testing yourself against your own input paths rather than taking on faith. The second is class-JPA-style persistence: annotate a class with @Table, @Id and @Column, inject ReactiveRepository<MyEntity, String>, and you get create, read, update and delete without writing a mapper. Permissions are applied with annotations at the controller, as in the README's @PostMapping("/account") with @SaveAction on a method returning Mono<String>. The README lists RBAC permission control and data permission control as done, and two-factor verification as unchecked.

Installing hsweb-framework and getting a first entity working

The README is explicit that you should not clone the repository and modify it. It says the project has too many modules, that cloning and running is not recommended, and that you should instead use it through Maven dependencies, selecting only the modules you need. The README also states that after the official release, all modules will be published to the Maven Central repository, so the first thing to confirm is that the artifact you want is actually resolvable at the version you intend to use. Given that, the practical starting point is a Spring Boot 2 application with the modules you need on the classpath. The README does not print a dependency snippet or module coordinates, so check the repository's pom.xml and the individual module READMEs before wiring anything up. What the README does give is the entity and repository pattern, starting with an entity declared the way the README shows: a class annotated with @Table, a field annotated with @Id, and fields annotated with @Column. The example in the README uses s_entity as the table name, a String id, a String name and a Long createTime.

@Table(name = "s_entity")
public class MyEntity {
    
    @Id
    private String id;
    
    @Column
    private String name;

    @Column
    private Long createTime;
}

Injecting the repository is then enough for CRUD, according to the README, which shows the repository injected with @Autowire and typed as ReactiveRepository<MyEntity, String>. The README does not document schema generation or migration for that table, so you should expect to create it yourself and check the module README for details.

@Autowire
private ReactiveRepository<MyEntity, String> repository;

For a first real endpoint, the README's permission example is the pattern to copy: a @PostMapping method that takes a Mono<Account> request body, carries a permission annotation such as @SaveAction, and returns a Mono.

@PostMapping("/account")
@SaveAction
public Mono<String> addAccount(@RequestBody Mono<Account> account){
     return accountService.doSave(account);
}

The repository also points to an examples project at github.com/zhou-hao/hsweb4-examples, which is the place to look for a runnable arrangement of these pieces.

Where hsweb-framework is the wrong choice

The README's own checklist is the clearest limitation. Non-reactive support for MVC and JDBC is unchecked. If your application is built on Spring MVC and blocking JDBC, hsweb-framework does not offer a gradual path: the reactive transaction control and the R2DBC-based CRUD assume the reactive stack throughout. Two-factor verification is also unchecked, so a deployment that requires it will have to build that layer itself. The built-in business features are partial. Permission management covers user management, permission settings and permission assignment, and the data dictionary is done, but file upload is split: static file upload is checked and instant upload is not. The README's own framing reinforces the point: the project has many modules and was not designed to be cloned and modified. That is a real constraint if your team's habit is to fork a framework and edit it in place. And the reactive requirement is not a stylistic preference. Debugging stack traces across Reactor operators, reasoning about backpressure, and keeping blocking calls out of the event loop are ongoing costs that a Spring MVC application never pays.

How hsweb-framework differs from JPA-based admin starters

The obvious alternative for a Java admin backend is a Spring Boot starter built around Spring Data JPA and Spring MVC. The difference is not the feature list; it is the execution model. A JPA-based starter runs each request on a servlet thread, blocks on the JDBC connection, and returns the result. hsweb-framework runs the request through WebFlux, executes queries through R2DBC, and returns a Mono or Flux that the caller composes. That changes how you write transactions, how you handle errors, and how you test. It also changes what you can do with a slow downstream: in the reactive model you compose, in the blocking model you wait. The second difference is the query layer. JPA gives you a criteria API and JPQL; hsweb gives you the DSL shown in the README, where createQuery().where("name",name).fetch() builds the predicate from a field name and a value. That is faster to write for straightforward filters and less expressive for complex joins, and the README does not document the boundary. If your team has no Reactor experience, a JPA-based starter will get you to a working admin panel sooner, and the cost of hsweb's model will show up before the benefit does.

Maintenance status, licence and upgrade cost

The repository is not archived, and the last push was on 2026-11-02, which is recent. Recent releases listed are 5.0.2 from 2026-10-21, 4.0.20 from 2025-10-27, and 5.0.1 from 2025-10-27. Note the shape of that list: two release lines, 5.0.x and 4.0.x, with 4.0.20 and 5.0.1 published within about 35 minutes of each other. The README still carries the heading "hsweb4" and its easy-orm link points at the 4.0.x branch, while the newest release is 5.0.2 and the default branch is 5.0.x. Anyone adopting this should decide which line they are on before writing code, because the README's examples and the newest release are not obviously the same generation. The README also states that all modules will be published to Maven Central after the official release, which means availability of a specific module at a specific version is something to verify rather than assume. The licence is Apache-2.0, per the repository's LICENSE file and the README's licence link. That is a permissive licence, but it says nothing about the licence of your own application, and nothing here is legal advice. The upgrade cost is structural: because the framework is consumed as Maven modules rather than forked, a version bump is a dependency change, but it also means you cannot patch a module locally without abandoning that model.

Editorial conclusion

Adopt hsweb-framework if your team already writes Reactor and WebFlux code and wants reactive CRUD, RBAC and data permissions as Maven dependencies instead of a fork. Do not adopt it if you are on Spring MVC or blocking JDBC: the README lists non-reactive MVC and JDBC support as unchecked, so the framework will not meet you there. Before committing, verify that the module you need is published to Maven Central at the version you intend to use, since the README states all modules will be published there only after the official release, and read the README.md inside each module you plan to depend on.

Frequently asked questions

Official sources

1. hs-web/hsweb-framework on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases