Overview
HiAPI is a Java application framework for multi-tenant SaaS systems, built on Spring Boot 3 and Spring Cloud. It targets a specific kind of repeated work: every new SaaS product ends up reimplementing tenant isolation, paginated queries, authorization, file uploads, SMS delivery, event notification and database sharding — and getting those right costs far more than it looks.
HiAPI provides them as a base you inherit from and configure, so application code only carries what is genuinely business logic.
Runtime requirements
| Item | Version |
|---|---|
| JDK | 21 |
| Spring Boot | 3.4.4 |
| Spring Cloud | 2024.0.0 |
| Database | MySQL (accessed through ShardingSphere) |
| Cache | Redis |
Capability map
The framework is a set of independent modules; pull in only what you need.
Core
| Module | Provides |
|---|---|
hiapi-core-basic | Base entities, unified response envelope, account types, field-update descriptors |
hiapi-core-exception | Unified exceptions and error codes |
hiapi-core-language | i18n message sources |
hiapi-core-utils | General utilities |
Data access
| Module | Provides |
|---|---|
hiapi-core-service | BasicService / AbsBasicService domain service bases |
hiapi-core-query | QueryWrapper condition building, paged requests, tenant-scoped query bases |
hiapi-core-sharding | Sharding configuration: by time or by a chosen column |
hiapi-core-sharding-service | Service-layer support and table-creation tasks for sharded tables |
hiapi-core-redis | Cache abstraction |
Web layer
| Module | Provides |
|---|---|
hiapi-core-controller | BasicQueryController / BasicCurdController |
hiapi-core-application | Startup auto-configuration |
Security
| Module | Provides |
|---|---|
hiapi-core-security | Token filter, URL-to-role authorization, open API manifest |
hiapi-core-security-token | Token issuing and parsing |
hiapi-core-login | Login, registration, password change and recovery, with pre/post hooks and events |
hiapi-core-captcha-basic | Slider captcha with behavioural trace verification |
Infrastructure
| Module | Provides |
|---|---|
hiapi-core-upload | File upload: local / OSS / COS / S3, pre-signed direct upload and callbacks |
hiapi-core-sender | SMS and email delivery with delivery records |
hiapi-core-dispatch | Cross-service SPI dispatch, Redis distributed locks |
hiapi-core-event-sdk | Event publish/subscribe with MQ routing |
hiapi-core-iot-mqtt | MQTT device connectivity (including AWS IoT) |
hiapi-core-operation-log | Annotation-driven operation logging |
hiapi-core-thirdparty-api | Third-party platform integration |
hiapi-core-app-install | Sub-application installation, menu and link registration |
Core concepts
1. CRUD by inheritance
A business controller extends a base class and declares its generics. Paged query, fetch by id, create, update and delete are available immediately:
@RestController
@RequestMapping("/merchant/product")
public class ProductController
extends BasicCurdController<Product, Long, ProductVo, ProductQuery> {
}Override hooks where behaviour differs, rather than replacing the base:
| Hook | When it runs |
|---|---|
getMid() | Resolve the current tenant key |
parseData(...) | Map request fields onto the entity before save |
buildFields(...) | Build the set of fields to update |
toListVo(...) / toDataVo(...) | Map entities to response objects |
saveCallback(...) | Post-save logic, inside the same transaction |
deleteBeforeIntercept(...) | Validation before delete |
2. Multi-tenancy in the foundation
Four account types, where the path prefix is the permission boundary:
| Prefix | Account type |
|---|---|
/merchant/** | Merchant |
/user/** | End user |
/channel/** | Channel |
/platform/** | Platform |
Every business record carries a tenant key. The current tenant and identity come from the token:
Long mid = TokenGet.getMid(); // tenant key
Long fid = TokenGet.getFid(); // current account3. Updates describe fields, not whole objects
This avoids the lost-update problem inherent in read-modify-write:
service.update(
UpdateFields.newBuilder().put("status", 1).build(),
QueryWrapper.create().eq("mid", mid).eq("id", id)
);4. Two layers of authorization
- Account type — coarse-grained checks by path prefix and annotation, applied service-wide
- Role / menu — fine-grained URL-to-role rules evaluated per request; changes take effect within 60 seconds without a restart
5. Cross-service calls go through SPI
Services never depend on another service's client classes directly:
ICloudMerchantService merchant = dispatchContext.getCloudService(ICloudMerchantService.class);A local implementation takes precedence over the remote one, so the same business code runs in both monolithic and microservice deployments.
Licensing
HiAPI is proprietary commercial software. Publishing artifacts to Maven Central exists so that licensed customers — particularly those outside mainland China who cannot reach a private repository — can resolve dependencies directly. It does not grant any license to the public.
The -sources and -javadoc attachments published alongside the artifacts are intentionally empty placeholders and contain no source code.
See Licensing.