xpc

XPC: Next-Gen Go Microservice Framework

XPC 是一个受 Google Service Weaver 启发，专为 Go 语言打造的现代、高性能、零依赖的微服务开发框架。

它的核心理念是："像开发单体应用一样开发微服务，运行时既可以单体发布运行，也可以像管理集群一样管理运行时部分或者全部。"

我们推崇 约束大于配置 (Convention over Configuration)，通过代码层面的最佳实践约束，消除繁琐的配置文件，让开发者专注于业务逻辑。

核心特性 (Features)

• 逻辑单体，物理分布 (Logical Monolith, Physical Distribution)

  • 开发者编写代码如同在写一个模块化的单体应用。
  • 灵活部署：编译出的二进制文件既可以直接作为单体应用在单机运行（生产级性能，本地函数调用），也可以通过运行时配置，将特定组件动态拆分到不同节点上运行。
  • 生命周期管理：内置 Init(ctx) 和 Shutdown(ctx) 生命周期钩子，确保资源正确初始化和释放。

• 零外部依赖 (Zero Dependencies)

  • 完全基于 Go 标准库构建。
  • 拒绝臃肿，追求极致的轻量化和编译速度。

• Raft 驱动的智能运行时 (Raft-Powered Runtime)

  • (Planned) 集成高性能 Raft 共识算法。
  • 去中心化元数据管理：无需依赖外部 Etcd 或 Consul。
  • 安全优先：内置 TLS 支持，确保集群通信安全。

• 极简代码风格 (Minimalist API)

  • 直觉化 API: xpc.Run 自动处理依赖注入和优雅退出 (Graceful Shutdown)。
  • 自动化: xpc gen 自动生成注册代码，减少样板。
  • 扁平化结构: 源码结构扁平，核心逻辑文件平铺在项目根目录，拒绝深度嵌套。

架构设计 (Architecture)

XPC 框架经过深度优化，分为三层：

1. API 层 (Public API)

提供极其精简的接口：

• xpc.Implements[T]: 标记组件实现。

• xpc.Run(ctx, app, opts...): 启动应用，自动处理信号、生命周期和依赖注入。

  type Calculator interface {
  Add(ctx context.Context, a, b int) (int, error)
  }
  

2. 核心运行时 (Core Runtime)

位于根目录的 runtime.go 和 registry.go，高度模块化但结构扁平：

• Local Runtime: 针对单机模式极致优化，组件间通信为直接内存函数调用，零网络开销。
• Cluster Runtime: (开发中) 基于 Raft 的分布式运行时，支持 mTLS 安全通信。
• Registry: 线程安全的组件注册中心，支持热加载准备。

3. 工具链 (Toolchain)

cmd/xpc 提供代码生成工具，扫描源码并自动注册组件。

项目结构规范 (Project Structure)

我们遵循极简的扁平化目录结构：

• 核心库文件：所有核心 .go 文件平铺在项目根目录（如 xpc.go, runtime.go, registry.go）。
• cmd/: 存放 CLI 工具入口。
• example/: 存放示例代码。
• 无 internal/: 除非绝对必要，否则不使用深层嵌套的 internal 目录，通过大小写控制可见性。

快速开始 (Getting Started)

1. 定义组件

package main

import (
    "context"
    "fmt"
    "igit.com/robert/xpc"
)

// 定义接口
type HelloService interface {
    SayHello(ctx context.Context, name string) (string, error)
}

// 实现接口
type helloServiceImpl struct {
    xpc.Implements[HelloService]
}

// 可选：初始化钩子
func (h *helloServiceImpl) Init(ctx context.Context) error {
    fmt.Println("Service Initialized")
    return nil
}

func (h *helloServiceImpl) SayHello(ctx context.Context, name string) (string, error) {
    return "Hello, " + name, nil
}

2. 运行应用

func main() {
    // 启动 XPC，自动处理依赖注入和优雅退出
    err := xpc.Run(context.Background(), func(ctx context.Context, hello HelloService) error {
        res, _ := hello.SayHello(ctx, "World")
        println(res)
        return nil // 返回后 XPC 会自动执行 Shutdown
    })
    
    if err != nil {
        panic(err)
    }
}

3. 生成代码与运行

# 生成注册代码
go run cmd/xpc/main.go gen

# 运行
go run .

安全与配置 (Security & Config)

XPC 优先考虑安全性。在启动时可以配置 TLS 证书，供集群模式使用：

xpc.Run(ctx, app, xpc.Options{
    TLSCertFile: "/path/to/cert.pem",
    TLSKeyFile:  "/path/to/key.pem",
})

路线图 (Roadmap)

• [x] Phase 1: Core Framework Refactoring

  • 模块化运行时架构 (Internal Runtime)。
  • 生命周期管理 (Init/Shutdown)。
  • 优雅退出与信号处理。
  • 基础依赖注入系统。
  • 扁平化项目结构。

• [ ] Phase 2: Distribution & Security

  • 实现 Cluster Runtime (Raft integration).
  • 实现 mTLS 通信层。
  • 完善 xpc gen 支持跨包接口。

贡献 (Contributing)

本项目遵循严格的代码规范：简洁、原生、高性能。