快速开始

本章将引导你从零开始搭建 JSaas 开发环境，创建并运行你的第一个 SaaS 模块。

📋 本章目标

  • 了解 JSaas 基座平台的核心概念
  • 完成本地开发环境的安装与配置
  • 使用 CLI 工具创建第一个模块项目
  • 在本地启动并预览模块运行效果

文档与资源

JSaas 采用前后端分离的一体化 SaaS 基座架构，仓库中包含文档站点、数据库脚本和接口规范，便于团队协作与多环境部署。

目录结构
docs/                              # 项目文档（基于 VitePress 静态站点生成器）
├── zh/                              # 中文文档
│   ├── development/                 # 开发文档
│   ├── architecture/                  # 架构文档
│   └── modules/                       # 模块市场文档
├── assets/                          # 文档图片等资源
├── index.md                         # 文档首页
└── package.json                     # 文档站点依赖

sql/                               # 数据库初始化脚本
├── jsaas-schema.sql             # 基座库表结构（含租户、用户、权限、模块）
└── jsaas-data.sql               # 初始数据（管理员账号、系统配置、默认菜单）

jsaas-module-spec.md             # 模块开发规范与接口协议（JSON Schema + 字段说明）

此结构设计遵循 高内聚、低耦合 原则，便于团队协作、功能扩展与多环境部署。如需自定义模块组合，请参考各 pom.xml 依赖声明。

快速定位建议

根据你的使用场景，选择最合适的入口项目，快速启动开发或集成：

场景推荐入口
本地全量开发JSaas-starter-all + JSaas-ui-admin
仅调试公开 APIJSaas-starter-public
集成对话/消息能力JSaas-ui-webapp + JSaas-api-public
扩展 AI 业务能力jsaas-module-ai + JSaas-common-ai

环境准备

在开始开发之前，请确保你的开发环境满足以下要求：

环境版本要求说明
JDK17+推荐 Amazon Corretto 17 或 OpenJDK 17
Maven3.8+项目构建与依赖管理
Node.js18+前端模块开发（如需前端页面）
MySQL8.0+数据库存储，支持多租户隔离
Redis6.0+缓存与会话管理（可选）

推荐使用 SDKMAN 管理 JDK 版本，使用 nvm 管理 Node.js 版本，可以方便地切换不同版本。

项目创建

1. 安装 JSaas CLI

JSaas CLI 是官方提供的命令行工具，帮助你快速创建、开发和发布模块。

bash
npm install -g @jsaas/cli

# 验证安装
jsaas --version

2. 创建模块项目

使用 CLI 初始化一个全新的模块项目，选择模块模板后会自动生成项目骨架。

bash
jsaas create my-first-module

# 交互式选择模板：
# ? 选择模块类型： (Use arrow keys)
# ❯ 通用业务模块（推荐）
#   后台管理模块
#   数据报表模块
#   API 服务模块

cd my-first-module

模块名称只能包含小写字母、数字和连字符（-），且必须以字母开头。例如：crm-module 、inventory-v2。

项目结构

初始化的项目包含以下目录结构：

目录结构
my-first-module/
├── pom.xml                    # Maven 配置，继承基座 Parent POM
├── module.json                # 模块元数据（名称/版本/描述/依赖）
├── src/
│   ├── main/
│   │   ├── java/
│   │   │   └── com/jsaas/module/
│   │   │       ├── ModuleApplication.java    # 启动类
│   │   │       ├── controller/               # REST API 控制器
│   │   │       ├── service/                  # 业务逻辑层
│   │   │       ├── repository/               # 数据访问层
│   │   │       └── config/                   # 模块配置
│   │   └── resources/
│   │       ├── application.yml               # 应用配置
│   │       └── db/migration/                 # 数据库迁移脚本
│   └── test/                                 # 单元测试
└── ui/                                       # 前端页面（可选）
    ├── package.json
    ├── src/
    │   ├── App.tsx
    │   └── pages/
    └── vite.config.ts

每个模块都继承基座的核心能力：多租户隔离、统一认证、权限控制和日志追踪均由基座自动提供，开发者只需关注业务逻辑实现。

本地运行

1. 配置数据库

编辑 src/main/resources/application.yml，配置数据库连接：

yaml
spring:
  datasource:
    url: jdbc:mysql://localhost:3306/jsaas_module
    username: root
    password: your_password
    driver-class-name: com.mysql.cj.jdbc.Driver

jsaas:
  base-platform:
    url: http://localhost:8080    # 基座平台地址
  module:
    name: my-first-module
    version: 1.0.0

2. 启动模块

bash
# 后端启动
mvn spring-boot:run

# 前端启动（如果包含 UI）
cd ui && npm install && npm run dev

启动成功后，后端服务默认运行在 http://localhost:8081，前端开发服务器运行在 http://localhost:5173。

基座平台启动后，模块会自动注册到基座的多租户环境中。你可以在基座管理后台看到已注册的模块，并进行租户分配和权限配置。

下一页基座架构
在 GitHub 上编辑此页