# comsdk

**Repository Path**: yuwenlwl/comsdk

## Basic Information

- **Project Name**: comsdk
- **Description**: 服务组件核心模块SDK
- **Primary Language**: Go
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-04-13
- **Last Updated**: 2025-04-13

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 服务组件SDK

服务组件SDK（comsdk）为服务组件开发提供核心功能，简化服务开发，提高代码复用率和质量。

## 功能特性

- **HTTP服务器**：提供基于gorilla/mux的路由管理、健康检查等功能
- **组件间通信**：提供加密的组件间通信能力
- **服务注册**：支持服务自动注册到API网关
- **安全验证**：提供请求签名和验证功能
- **统一错误处理**：标准错误码和响应格式
- **环境配置**：支持从.env文件自动加载配置

## 目录结构

```
comsdk/
├── server/          # 服务器功能
├── communication/   # 组件间通信功能
├── registry/        # 服务注册功能
├── security/        # 安全验证功能
├── config/          # 配置加载功能
├── example/         # 示例代码
├── scripts/         # 发布和维护脚本
├── go.mod           # 模块定义
├── go.sum           # 依赖校验
├── comsdk.go        # 主入口文件
├── errors.go        # 错误处理
├── Makefile         # 构建任务
└── README.md        # 说明文档
```

## 快速开始

### 安装

```bash
go get gitee.com/yuwenlwl/comsdk
```

### 推荐用法 (新)

新版SDK支持从.env文件自动加载配置，简化服务组件开发。

1. 首先在服务组件目录下创建一个`.env`文件：

```
# 必填项
APP_ID=your-service-id      # 服务组件ID
APP_SECRET=your-app-secret  # 服务组件密钥

# 可选项
APP_NAME=您的服务名称        # 服务组件名称
APP_PORT=8888              # 服务端口
APP_VERSION=1.0.0          # 服务版本
```

2. 使用简化的应用程序启动代码：

```go
package main

import (
	"context"
	"log"
	"net/http"
	"os"
	"os/signal"
	"syscall"
	"time"

	"gitee.com/yuwenlwl/comsdk"
)

func main() {
	// 初始化应用
	app, err := comsdk.InitApp("http://api-gateway.example.com", "/api/components")
	if err != nil {
		log.Fatalf("初始化应用失败: %v", err)
	}

	// 注册API路由
	app.Server.Router.HandleFunc("/hello", func(w http.ResponseWriter, r *http.Request) {
		comsdk.JSONResponse(w, http.StatusOK, map[string]interface{}{
			"message": "Hello from " + app.Config.AppID,
		})
	}).Methods("GET")

	// 启动信号处理
	ctx, cancel := context.WithCancel(context.Background())
	defer cancel()

	// 监听系统信号
	go func() {
		signalChan := make(chan os.Signal, 1)
		signal.Notify(signalChan, os.Interrupt, syscall.SIGTERM)
		<-signalChan

		log.Println("收到关闭信号，正在优雅关闭...")
		cancel() // 取消上下文，通知所有组件关闭
	}()

	// 启动应用（阻塞调用）
	if err := app.StartApp(ctx); err != nil && err != http.ErrServerClosed {
		log.Fatalf("服务器错误: %v", err)
	}
}
```

### 基本用法 (传统)

如果需要更多自定义控制，也可以使用传统的方式配置和启动服务组件：

```go
package main

import (
	"context"
	"log"
	"net/http"
	"os"
	"os/signal"
	"syscall"
	"time"

	"gitee.com/yuwenlwl/comsdk"
)

func main() {
	// 从环境变量或配置获取端口
	port := os.Getenv("SERVICE_PORT")
	if port == "" {
		port = "8888" // 默认端口
	}

	// 创建安全验证器
	verifier := comsdk.NewVerifier("your-app-id", "your-app-secret")

	// 创建服务器
	server := comsdk.NewServer("1.0.0", verifier)

	// 注册路由
	server.Router.HandleFunc("/hello", func(w http.ResponseWriter, r *http.Request) {
		comsdk.JSONResponse(w, http.StatusOK, map[string]string{
			"message": "Hello World!",
		})
	}).Methods("GET")

	// 添加中间件
	server.Router.Use(server.GatewayAuthMiddleware)

	// 服务地址
	serviceHost := os.Getenv("SERVICE_HOST")
	if serviceHost == "" {
		serviceHost = "localhost" // 默认主机名
	}
	serviceAddr := serviceHost + ":" + port
	serviceURL := "http://" + serviceAddr

	// 启动服务器（非阻塞）
	go func() {
		log.Printf("服务器正在启动，监听端口: %s", port)
		if err := server.Start(port); err != nil {
			log.Fatalf("服务器启动失败: %v", err)
		}
	}()

	// 注册服务组件到网关
	componentInfo := comsdk.ComponentInfo{
		AppID:          "your-app-id",
		Name:           "your-service",
		Description:    "Your service description",
		Version:        "1.0.0",
		ServiceURL:     serviceURL,
		HealthCheckURL: serviceURL + "/health",
	}

	registrar := comsdk.NewRegistrar(
		componentInfo,
		"http://api-gateway.example.com",
		"/register",
		verifier,
	)

	if err := registrar.Register(); err != nil {
		log.Printf("注册服务失败: %v", err)
	}

	// 启动心跳服务
	ctx, cancel := context.WithCancel(context.Background())
	go registrar.StartHeartbeat(ctx, 30*time.Second)

	// 优雅关闭
	quit := make(chan os.Signal, 1)
	signal.Notify(quit, syscall.SIGINT, syscall.SIGTERM)
	<-quit

	// 取消心跳
	cancel()

	// 注销服务
	if err := registrar.Deregister(); err != nil {
		log.Printf("注销服务失败: %v", err)
	}

	// 关闭服务器
	shutdownCtx, shutdownCancel := context.WithTimeout(context.Background(), 5*time.Second)
	defer shutdownCancel()
	if err := server.Stop(shutdownCtx); err != nil {
		log.Fatalf("服务器关闭失败: %v", err)
	}
}
```

## 主要功能使用说明

### 服务器

```go
// 创建服务器
server := comsdk.NewServer("1.0.0", verifier)

// 注册健康检查
server.HealthManager.RegisterCheck("database", func() (bool, string) {
    // 执行数据库连接检查
    return true, "数据库连接正常"
})

// 注册路由
server.Router.HandleFunc("/api/data", handleData).Methods("GET")

// 启动服务器
server.Start("8080")

// 停止服务器
ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()
server.Stop(ctx)
```

### 组件间通信

```go
// 设置共享密钥
comsdk.SetSharedSecret("your-shared-secret")

// 创建请求
req := comsdk.NewRequest(
	"http://another-service:8080", 
	"/api/data", 
	"POST", 
	map[string]interface{}{
		"key": "value",
	},
)

// 发送请求
resp, err := req.Send()
if err != nil {
	log.Printf("请求失败: %v", err)
	return
}

// 处理响应
if !resp.Success {
	log.Printf("请求错误: %s", resp.Message)
	return
}

log.Printf("响应数据: %v", resp.Data)
```

### 服务注册

```go
// 创建服务信息
componentInfo := comsdk.ComponentInfo{
    AppID:          "your-app-id",
    Name:           "your-service",
    Description:    "Your service description",
    Version:        "1.0.0",
    ServiceURL:     "http://localhost:8080",
    HealthCheckURL: "http://localhost:8080/health",
}

// 创建注册器
registrar := comsdk.NewRegistrar(
    componentInfo,
    "http://api-gateway.example.com",
    "/register",
    verifier,
)

// 注册服务
if err := registrar.Register(); err != nil {
    log.Printf("注册服务失败: %v", err)
}

// 启动心跳
ctx, cancel := context.WithCancel(context.Background())
go registrar.StartHeartbeat(ctx, 30*time.Second)

// 注销服务
if err := registrar.Deregister(); err != nil {
    log.Printf("注销服务失败: %v", err)
}
```

### 错误处理

```go
// 创建应用错误
err := comsdk.NewAppError(
	comsdk.ErrCodeNotFound, 
	"资源不存在", 
	"请求的ID不存在", 
	nil,
)

// 发送错误响应
comsdk.SendErrorResponse(w, err, "trace-123")

// 包装其他错误
if dbErr != nil {
	appErr := comsdk.WrapError(dbErr, comsdk.ErrCodeSystem, "数据库操作失败")
	comsdk.SendErrorResponse(w, appErr, "trace-123")
	return
}
```

## 版本管理

### 版本规则

SDK采用语义化版本控制(Semantic Versioning)：

- **主版本号(X.y.z)**：不兼容的API变更
- **次版本号(x.Y.z)**：向后兼容的功能新增
- **修订版本号(x.y.Z)**：向后兼容的问题修复

### 在项目中升级SDK

```bash
# 升级到最新版本
go get -u gitee.com/yuwenlwl/comsdk

# 升级到特定版本
go get gitee.com/yuwenlwl/comsdk@v1.2.3

# 整理依赖
go mod tidy
```

## 本地开发调试

如果需要同时开发SDK和服务组件，可以使用`replace`指令：

```go
// go.mod
module example.com/my-service

go 1.18

require (
    gitee.com/yuwenlwl/comsdk v1.0.0
)

// 使用本地SDK版本进行开发
replace gitee.com/yuwenlwl/comsdk => ../path/to/local/comsdk
```

## 版本发布

使用Makefile简化版本发布流程：

```bash
# 发布新补丁版本（1.0.0 -> 1.0.1）
make release-patch

# 发布新次要版本（1.0.0 -> 1.1.0）
make release-minor

# 发布新主要版本（1.0.0 -> 2.0.0）
make release-major

# 手动选择版本类型
make release
```

## 贡献指南

欢迎通过以下方式贡献代码：

1. Fork此仓库
2. 创建您的特性分支 (`git checkout -b feature/amazing-feature`)
3. 提交您的更改 (`git commit -m 'Add some amazing feature'`)
4. 推送到分支 (`git push origin feature/amazing-feature`)
5. 打开Pull Request

## 许可证

MIT