跳至主要內容

项目工程规范

本文档主要介绍项目开发规范以及构建成品的标准规范。

开发项目工程规范

在项目开发过程中，良好的工程结构至关重要，它能够帮助开发者快速定位问题，降低项目复杂度，提高开发效率。

前端开发规范

前端开发时请遵循以下目录结构规范，所有前端项目文件需要放置在项目根目录下的 web 目录中：

HTML
web/
├── index.html    # 主入口 HTML 文件
└── build.sh      # 构建脚本

后端开发规范

后端开发时请遵循以下 Go 工程目录结构规范，所有后端项目文件放置在 backend 目录下：

backend/
├── main.go               # 程序入口：解析 socket 路径，创建并启动 RPC Server
├── Makefile              # 后端编译、运行与交叉编译打包脚本
├── config.json           # 环境配置 (test/prod 双环境，日志与运行时选项)
├── go.mod / go.sum       # Go 依赖包管理文件
├── i18n/                 # 国际化语言文件
│   ├── zh-CN.ini         # 中文翻译包
│   └── en.ini            # 英文翻译包
├── internal/             # 核心业务代码（强制单向分层，禁止反向依赖）
│   ├── common/           # 应用公共常量 (AppName, OrgName, GMSSH 路径规则, 错误码)
│   ├── core/adapter/     # 外部适配器 (数据库驱动、外部服务或底层命令封装)
│   ├── dto/              # 数据传输对象 (XxxReq / XxxResp，入参自动绑定校验)
│   ├── handler/rpc/      # 接入层：RPC 路由注册 (server.go) 与方法处理器
│   ├── model/            # 业务数据模型与实体定义
│   └── service/          # 核心业务逻辑层 (NewXxxService 工厂模式)
├── pkg/                  # 公共工具库
│   ├── files/            # 安全文件操作封装（内置路径防穿透检查）
│   └── rpcutil/          # RPC 请求反序列化与 i18n 语言上下文绑定工具
├── data/                 # 运行时数据目录 (本地调试与打包时自动创建)
├── logs/                 # 运行时日志目录 (本地调试与打包时自动创建)
└── tmp/                  # 运行时临时文件目录 (本地调试 socket 存放位置)

强制分层调用规则

handler (接入层)        ← 接收 RPC 请求，解析参数，返回响应
   ↓ 调用
service (业务逻辑层)    ← 核心业务实现，编排 model 和 adapter
   ↓ 调用
model (数据模型层)      ← 业务实体定义
   ↓ 使用
core/adapter (基础设施) ← 外部服务封装（DB、底层命令等）
  • 上层调用下层，严禁反向依赖；common/ 和 dto/ 为公共契约层，可被任意层引用。
  • Handler 不含复杂业务，Service 不直接处理底层 RPC 请求对象。

完整项目结构

微应用统一在同一个 Git 仓库中管理前后端代码，标准仓库目录结构如下：

my-gmssh-app/
├── web/                  # 前端目录
│   ├── index.html        # 主入口 HTML 文件（或 Vue / React 源码工程）
│   ├── build.sh          # 前端自动化构建与打包脚本
│   └── README.md         # 前端说明
├── backend/              # Go 后端工程目录
│   ├── main.go           # 后端服务入口
│   ├── Makefile          # 后端编译与交叉构建脚本
│   ├── config.json       # 环境配置文件
│   ├── go.mod / go.sum   # 模块依赖
│   ├── i18n/             # 多语言文件
│   ├── internal/         # 内部业务逻辑（分层架构）
│   └── pkg/              # 公共工具函数库
├── install.sh            # 应用安装/初始化脚本（可选，上架部署时由平台自动调用）
├── makefile              # 项目根构建调度脚本
└── README.md             # 项目说明文档

应用成品规范

为了确保应用的一致性和标准化，在执行构建打包时，生成物必须按照以下规范组织成微应用包（ZIP）：

构建产物部署规范

在执行构建脚本后，构建产物统一输出在应用包内：

  • 后端构建产物：编译为静态二进制文件并放置在 app/bin/ 目录下，主可执行文件必须命名为 main
  • 前端构建产物：打包后放置在 app/www/ 目录下，主入口文件必须命名为 index.html
  • Socket 文件规则：后端生成的 socket 文件必须放置在 tmp/ 目录下并命名为 app.sock，平台健康检查与前端请求将按此路径自动路由寻址。
应用成品安装目录/
├── app/                  # 应用程序目录
│   ├── bin/              # 可执行文件目录
│   │   └── main          # Go 编译生成的 Linux 二进制程序 (无依赖)
│   └── www/              # Web 静态资源目录
│       └── index.html    # 前端入口页面及静态资源
├── config/               # 运行时配置文件目录 (包含 config.json)
├── data/                 # 数据存储目录
├── logs/                 # 日志文件目录 (按天切分日志)
└── tmp/                  # 临时文件目录 (包含 app.sock 套接字文件)

应用部署与数据分离机制

微应用在极目桌面中是直接安装并运行在目标 Linux 服务器上的，为了规范管理与系统安全，极目桌面统一采用 /.__gmssh 作为根工作区。

在此基础上，极目桌面实行了严格的**「程序与数据物理隔离」**机制：

/.__gmssh/
├── plugin/{组织名}/{应用名}/        # 【应用安装目录】存放二进制程序、前端代码、模板与临时 socket
└── data/plugin/{组织名}/{应用名}/   # 【应用数据目录】存放应用持久化数据（如 SQLite、用户文件、持久缓存）

为什么要做程序与数据分离？

  • 保护用户数据安全：如果将用户生成的数据或数据库保存在应用安装目录下，一旦用户卸载或升级该微应用，整个应用安装目录被清除时会导致数据意外丢失。
  • 平滑升级与回滚：微应用更新版本时，平台仅需安全覆盖安装目录下的程序文件，而用户的数据目录完好无损，做到真正的无损升级。
  • 开箱即用：在 Go 后端脚手架的 internal/common/constant.go 中，已直接通过 common.DataAppPath 提供了数据目录路径常量，编写涉及本地持久化存储的代码时，请务必将数据写入该路径下。
  • 应用安装目录：/.__gmssh/plugin/{组织名}/{应用名}/
  • 应用数据目录：/.__gmssh/data/plugin/{组织名}/{应用名}/
  • Socket 通信路径：/.__gmssh/plugin/{组织名}/{应用名}/tmp/app.sock
Copyright © 2026 极目Linux桌面团队