# 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...)`: 启动应用，自动处理信号、生命周期和依赖注入。

```go
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. 定义组件

```go
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. 运行应用

```go
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. 生成代码与运行

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

# 运行
go run .
```

## 安全与配置 (Security & Config)

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

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

## 路线图 (Roadmap)

- [x] **Phase 1: Core Framework Refactoring**
    - [x] 模块化运行时架构 (Internal Runtime)。
    - [x] 生命周期管理 (`Init`/`Shutdown`)。
    - [x] 优雅退出与信号处理。
    - [x] 基础依赖注入系统。
    - [x] 扁平化项目结构。

- [ ] **Phase 2: Distribution & Security**
    - [ ] 实现 Cluster Runtime (Raft integration).
    - [ ] 实现 mTLS 通信层。
    - [ ] 完善 `xpc gen` 支持跨包接口。

## 贡献 (Contributing)

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