快速开始

本页用一个最小可运行的服务,演示从空工程到第一个分页接口。

使用前须取得授权

HiAPI 是专有商业软件。构件可从 Maven Central 公开获取,但获取不等于获得授权, 正式使用前请先完成商业授权。详见授权说明。

前置条件

• JDK 21
• Maven 3.9+
• MySQL 与 Redis 各一个可用实例

一、引入框架

把框架作为 parent,即可继承全部依赖版本管理。不需要配置任何私有仓库—— 构件在 Maven Central 上,那是 Maven 的默认仓库。

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

然后按需引入模块。一个典型的 Web 服务通常需要:

<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>

版本号由 parent 统一管理,这里不写 <version>。

二、启动类

继承框架提供的启动基类,它已经带了 @SpringBootApplication,不要重复标注:

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() {
        // 启动完成后的初始化逻辑,可选
    }
}

微服务部署(接入注册中心、需要跨服务调用)时改为继承 BasicCloudApplication。

三、最小配置

spring:
  application:
    name: demo-service

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

  data:
    redis:
      host: 127.0.0.1
      port: 6379

  hiapi:
    security:
      url-role:
        # 细粒度授权需要本服务提供 URL→角色规则源。
        # 尚未提供时显式声明 none,否则框架会在启动时拒绝启动 ——
        # 这是刻意设计,避免"以为有权限控制、实际没有"的情况悄悄上线。
        mode: none

# traceId 需要这一行才会出现在日志里
logging:
  pattern:
    level: "%5p [%X{traceId:-}]"

四、第一个接口

定义实体与查询对象后,Controller 继承基类即可:

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

    @Override
    protected Long getMid() {
        return TokenGet.getMid();   // 租户隔离键
    }

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

启动后即可获得:

方法与路径	作用
GET /merchant/product/query	分页查询(带条件与排序)
GET /merchant/product/get	按 id 取详情
POST /merchant/product/save	新增
POST /merchant/product/update	修改
DELETE /merchant/product/delete	删除

只需要查询能力而不希望暴露写接口时,继承 BasicQueryController 即可。

五、写入用字段描述

更新时不要读出整个对象再存回去,直接描述要改的字段,避免并发覆盖:

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

下一步

• 框架概览 —— 完整能力地图与核心概念
• 授权说明 —— 使用前必读