快速开发应用

本文将以官方脚手架模板（包含前端页面与 Go 后端）为基准，带您快速了解极目桌面微应用的项目结构、前后端通信机制与本地极速开发流程。

适用场景

• 已在控制台创建微应用并获取专属 Git 仓库
• 希望快速掌握工程目录、前后端联调与极简编码闭环
• 基于官方 Go 脚手架进行二次业务开发

前置准备

1. 创建应用与获取脚手架

在极目桌面开发者中心创建应用时，选择前端模板并按需开启 Go 后端模板，即可获得初始化好的全套脚手架代码：

创建步骤

1. 登录 开发者中心
2. 在「控制面板」或「应用管理」点击「创建新应用」
3. 填写应用基本信息，并在选择技术栈时选择前端模板并勾选 Go 后端模板
4. 点击「创建应用」，系统将为您生成专属 Git 仓库

如果您还不熟悉应用创建流程，请先查看 应用模板创建指南。

2. 标准工程目录结构

将 Git 仓库克隆到本地后，您会看到如下清晰规范的微应用工程目录（前后端统一存放在同一个仓库中）：

微应用根目录/
├── web/                    # 前端项目目录
│   ├── index.html          # 前端页面入口（演示 $gm 调用与 RPC 请求）
│   ├── build.sh            # 前端自动化构建打包脚本
│   └── README.md           # 前端说明
├── backend/                # Go 后端工程目录 (Go 1.24+)
│   ├── main.go             # 程序入口：解析 socket 路径，启动 RPC Server
│   ├── Makefile            # 后端编译、运行与交叉打包脚本
│   ├── config.json         # 环境配置 (test/prod 双环境)
│   ├── go.mod / go.sum     # Go 模块依赖定义
│   ├── i18n/               # 国际化语言包 (zh-CN.ini / en.ini)
│   ├── internal/           # 核心业务逻辑 (强制分层架构)
│   │   ├── common/         # 应用常量 (AppName、路径规则、错误码)
│   │   ├── dto/            # 请求与响应结构体 (XxxReq / XxxResp)
│   │   ├── handler/rpc/    # RPC 方法注册与请求处理器 (接入层)
│   │   ├── service/        # 核心业务逻辑实现 (工厂工厂模式)
│   │   ├── model/          # 业务数据实体定义
│   │   └── core/adapter/   # 基础设施适配器 (DB、底层命令等)
│   └── pkg/                # 通用工具库 (pkg/files, pkg/rpcutil)
├── install.sh              # 应用安装/初始化脚本（可选）
├── makefile                # 根目录构建调度文件
└── README.md               # 项目说明文档

---

核心通信机制说明

极目桌面微应用的前后端通信采用轻量、高性能、免端口冲突的 Unix Domain Socket + JSON-RPC 2.0 架构：

[ 微应用前端 (web) ] 
       │  $gm.request('hello', { name: '极目' })
       ▼
[ 极目桌面客户端主进程 ]
       │  透明代理转发 (Unix Socket 文件)
       ▼
[ Go 后端守护进程 (backend) ] (基于 simplejrpc-go 注册的方法路由响应)

• 无网络端口占用：通信落在本地套接字文件上，不会与其他服务抢占端口。
• 免 CORS 跨域：前后端请求由桌面客户端安全桥接，开发时无需配置繁琐的代理和跨域头。
• 内置健康检查：Go 后端模板默认实现并注册了 ping 方法，供客户端检测后端常驻状态。

---

核心代码实现

1. Go 后端服务（基于 simplejrpc-go）

后端模板已经内置完整的 RPC 服务初始化骨架与标准路由注册。

程序入口 (backend/main.go)

在 main.go 中，程序调用 common.DefaultSockPath() 解析 Socket 地址，由 simplejrpc-go 底层自动管理 Socket 监听并支持收到 SIGINT / SIGTERM 信号时优雅退出与日志记录：

package main

import (
	"fmt"

	"github.com/DemonZack/simplejrpc-go/core"

	"app-skeleton-backend-go/internal/common"
	"app-skeleton-backend-go/internal/handler/rpc"
)

func main() {
	// 默认解析运行环境对应的 socket 路径（本地调试为 ./tmp/app.sock，安装后为平台约定路径）
	sock := common.DefaultSockPath()

	// 创建 RPC Server 并注册服务
	server := rpc.NewServer()

	// 启动服务（阻塞运行，收到 SIGINT/SIGTERM 信号自动优雅退出）
	if err := server.Start(sock); err != nil {
		core.Container.Log().Error(fmt.Sprintf("启动RPC服务器失败: %v", err))
		return
	}

	core.Container.Log().Info(fmt.Sprintf("服务启动成功, socket: %s", sock))
}

RPC 路由注册与处理器 (internal/handler/rpc/)

根据分层规范，Handler 只负责解析参数 → 调用 Service → 返回结果，不包含具体业务逻辑。

1. 在 server.go 中统一定义与注册路由（⚠️ ping 为平台健康检查接口，禁止修改或删除）：

// internal/handler/rpc/server.go
package rpc

import (
	"github.com/DemonZack/simplejrpc-go/net/gsock"
)

// RegisterHandles 注册所有 RPC 处理函数（路由名推荐使用 camelCase）
func (s *Server) RegisterHandles(ds interface {
	RegisterHandle(name string, handler func(*gsock.Request) (any, error), middlewares ...gsock.RPCMiddleware)
}) {
	// 基础接口（⚠️ ping 为平台健康检查接口，禁止删除或修改）
	ds.RegisterHandle("ping", s.Ping)

	// 业务接口
	ds.RegisterHandle("hello", s.Hello)
	ds.RegisterHandle("getItemList", s.GetItemList)
	ds.RegisterHandle("createItem", s.CreateItem)
	ds.RegisterHandle("deleteItem", s.DeleteItem)
}

// Ping 心跳检测 — GMSSH 平台健康检查接口（勿删除），禁止加入耗时逻辑
func (s *Server) Ping(req *gsock.Request) (any, error) {
	return "pong", nil
}

2. 在具体的 Handler 文件中处理前端请求（如 example_handler.go）：

// internal/handler/rpc/example_handler.go
package rpc

import (
	"app-skeleton-backend-go/internal/dto"
	"app-skeleton-backend-go/internal/service"
	"app-skeleton-backend-go/pkg/rpcutil"
	"github.com/DemonZack/simplejrpc-go/gsock"
)

// Hello 示例处理函数
func (s *Server) Hello(req *gsock.Request) (any, error) {
	var args dto.HelloReq
	// 自动将 JSON-RPC 参数解析到结构体中，并按请求自动设置 i18n 语言上下文
	if err := rpcutil.ParseParams(req, &args); err != nil {
		return nil, err
	}
	// 调用业务 Service 返回数据
	return service.NewExampleService().Hello(args)
}

---

2. 前端页面调用 (web/index.html)

前端页面通过极目桌面注入的全局 $gm 客户端桥接对象，即可直接向 Go 后端发起 RPC 调用：

<!DOCTYPE html>
<html lang="zh-CN">
<head>
  <meta charset="UTF-8" />
  <title>微应用前端示例</title>
  <script>
    // 页面加载完成后调用 Go 后端
    async function testCall() {
      if (!window.$gm || !window.$gm.request) {
        alert('请在极目桌面客户端中运行该页面');
        return;
      }

      try {
        // 1. 测试后端健康检查
        const pingRes = await window.$gm.request('ping');
        console.log('健康检查响应:', pingRes);

        // 2. 调用业务 hello 方法，传递参数
        const helloRes = await window.$gm.request('hello', { name: '极目桌面开发者' });
        document.getElementById('result').innerText = JSON.stringify(helloRes, null, 2);
      } catch (err) {
        console.error('RPC 请求失败:', err);
      }
    }
  </script>
</head>
<body>
  <h1>极目桌面微应用</h1>
  <button onclick="testCall()">调用 Go 后端接口</button>
  <pre id="result">等待调用...</pre>
</body>
</html>

---

本地极速联调与运行

克隆脚手架到本地后，您可以通过以下方式快速本地自测或接入极目桌面进行开发：

1. 后端本地启动

进入 backend 目录，执行：

cd backend

# 下载并整理 Go 依赖
make deps

# 启动本地开发服务 (默认监听 ./tmp/app.sock)
make run

当终端输出类似如下日志时，代表后端 Socket 服务启动成功：

[INFO] RPC server listening on ./tmp/app.sock
[INFO] Methods registered: ping, hello, getItemList, createItem, deleteItem

2. 自动化构建与编译

当开发完毕需要打包发布时：

• 打包前端：

  cd web && ./build.sh

• 交叉编译后端 Linux 可执行文件：

  cd backend && make build-linux

• 根目录一键打包：

  make all

  产物将自动整合输出到 dist/ 目录中，准备妥当即可直接提交审核发布。

下一步

若要在极目桌面客户端中实际关联本地正在开发的代码并开启实时调试，请前往 应用调试 - 快速上手。