Quick Start

A minimal runnable service, from an empty project to your first paginated endpoint.

A license is required before use

HiAPI is proprietary commercial software. Artifacts are publicly resolvable from Maven Central, but availability is not permission — obtain a commercial license before production use. See Licensing.

Prerequisites

• JDK 21
• Maven 3.9+
• A reachable MySQL instance and a Redis instance

1. Add the framework

Use the framework as your parent to inherit all managed dependency versions. No private repository configuration is needed — the artifacts are on Maven Central, which is Maven's default repository.

<parent>
    <groupId>cn.hiapi</groupId>
    <artifactId>hiapi-fast-frame</artifactId>
    <version>1.0.8</version>
</parent>

Then pull in the modules you need. A typical web service uses:

<dependencies>
    <dependency>
        <groupId>cn.hiapi</groupId>
        <artifactId>hiapi-core-application</artifactId>
    </dependency>
    <dependency>
        <groupId>cn.hiapi</groupId>
        <artifactId>hiapi-core-controller</artifactId>
    </dependency>
    <dependency>
        <groupId>cn.hiapi</groupId>
        <artifactId>hiapi-core-service</artifactId>
    </dependency>
    <dependency>
        <groupId>cn.hiapi</groupId>
        <artifactId>hiapi-core-security</artifactId>
    </dependency>
</dependencies>

Versions come from the parent, so no <version> here.

2. Application class

Extend the provided base class. It already carries @SpringBootApplication — do not add it again:

package com.example.demo;

import cn.hiapi.BasicApplication;
import org.springframework.boot.SpringApplication;

public class DemoApplication extends BasicApplication {

    public static void main(String[] args) {
        SpringApplication.run(DemoApplication.class, args);
    }

    @Override
    public void onStartup() {
        // optional post-startup initialisation
    }
}

For a microservice deployment (service registry, cross-service calls), extend BasicCloudApplication instead.

3. Minimal configuration

spring:
  application:
    name: demo-service

  datasource:
    url: jdbc:mysql://127.0.0.1:3306/demo?useUnicode=true&characterEncoding=utf8&serverTimezone=UTC
    username: your_user
    password: your_password

  data:
    redis:
      host: 127.0.0.1
      port: 6379

  hiapi:
    security:
      url-role:
        # Fine-grained authorization requires this service to supply URL-to-role rules.
        # Until it does, declare none explicitly — otherwise the framework refuses to start.
        # That is deliberate: it prevents a service shipping with authorization that
        # looks configured but never actually applies.
        mode: none

# traceId only appears in logs if this pattern is set
logging:
  pattern:
    level: "%5p [%X{traceId:-}]"

4. Your first endpoint

Define an entity and a query object, then extend the base controller:

@RestController
@RequestMapping("/merchant/product")
public class ProductController
        extends BasicCurdController<Product, Long, ProductVo, ProductQuery> {

    @Override
    protected Long getMid() {
        return TokenGet.getMid();   // tenant isolation key
    }

    @Override
    protected List<ProductVo> toListVo(List<Product> list) {
        return list.stream().map(ProductVo::of).toList();
    }
}

On startup you get:

Method and path	Purpose
GET /merchant/product/query	Paged query with filters and sorting
GET /merchant/product/get	Fetch by id
POST /merchant/product/save	Create
POST /merchant/product/update	Update
DELETE /merchant/product/delete	Delete

If you only want read access, extend BasicQueryController instead.

5. Write through field descriptors

Do not read an entity, mutate it and save it back — describe the fields to change:

service.update(
        UpdateFields.newBuilder().put("status", 1).build(),
        QueryWrapper.create().eq("mid", TokenGet.getMid()).eq("id", id)
);

Next

• Overview — full capability map and core concepts
• Licensing — read before use