# kratos

**Repository Path**: cuihovah/kratos

## Basic Information

- **Project Name**: kratos
- **Description**: No description available
- **Primary Language**: Go
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2025-10-12
- **Last Updated**: 2025-11-02

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 🚀 Kratos Web Framework

轻量级 Go Web 框架，支持 **动态接口注册、JWT 鉴权、MongoDB 事务管理、文件上传、统一错误处理**。  
适合构建中小型后端 API 服务，结构简洁、易扩展。

---

## ✨ 特性 Highlights

- ⚙️ **XML 动态路由注册**：无需手写 HTTP 路由，自动加载业务函数  
- 🔐 **JWT / Cookie 鉴权**：内置 Token 解析与用户验证  
- 💾 **MongoDB 原生事务支持**：配置即生效  
- 📂 **文件上传封装**：简洁接口快速集成  
- 💥 **统一错误与响应结构**：自动生成 trace_id 与堆栈追踪  

---

## 📁 目录结构

```

.
├── business/              # 业务逻辑模块
│   ├── serv.go            # 服务注册与实现入口
│   ├── access.go          # JWT 登录与鉴权
│   ├── uploads.go         # 文件上传接口
│   ├── error.go           # 错误处理演示
│   └── utils.go           # 辅助工具
│
├── repository/            # MongoDB 数据访问层
│   ├── repository.go
│   ├── transcation_log.go
│   └── transcation_record.go
│
├── schema/                # 数据结构定义
│   ├── user.go
│   └── schema.go
│
├── router/                # XML 路由配置文件
│   └── router.xml
│
├── conf.ini               # 服务配置文件
├── main.go                # 程序启动入口
└── go.mod

````

---

## ⚡ 快速开始（Quick Start）

### 1️⃣ 安装依赖

```bash
go mod tidy
````

---

### 2️⃣ 配置服务

编辑 `conf.ini`：

```ini
[main]
port = 8080

[mongodb]
url = mongodb://localhost:27017
dbname = kratos_demo
```

---

### 3️⃣ 定义路由（router/router.xml）

```xml
<Routes>
  <Route>
    <Method>login</Method>
    <Name>Login</Name>
    <Transcation>false</Transcation>
    <Authorization>false</Authorization>
  </Route>
  <Route>
    <Method>uploads</Method>
    <Name>Uploads</Name>
    <Transcation>false</Transcation>
    <Authorization>false</Authorization>
  </Route>
</Routes>
```

---

### 4️⃣ 实现业务逻辑

在 `business/serv.go`：

```go
func (s *Serv) Login(ctx context.Context, token kratos.Token, body []byte, query map[string]string) (interface{}, error) {
    var user schema.User
    _ = json.Unmarshal(body, &user)
    if user.Username != "admin" || user.Password != "123456" {
        return nil, kratos.NewError(401, "用户名或密码错误", nil)
    }

    jwtStr, _ := GenerateJWT(user, "my_secret", map[string]interface{}{
        "exp": time.Now().Add(24 * time.Hour).Unix(),
    })
    kratos.SetCookie(ctx, s.SessionName(), jwtStr)
    return bson.M{"token": jwtStr}, nil
}
```

---

### 5️⃣ 启动服务

```bash
go run main.go
```

输出示例：

```
[INFO] Kratos server started on port 8080
[INFO] Routes loaded: login, uploads
```

---

### 6️⃣ 测试接口

**登录：**

```bash
curl -X POST "http://localhost:8080/spdb_view/v1?method=login" \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"123456"}'
```

**上传文件：**

```bash
curl -X POST "http://localhost:8080/spdb_view/v1?method=uploads" \
  -F "file=@./test.png"
```

---

## 🔑 鉴权机制

* 支持 **Cookie + JWT 双模验证**
* 登录成功后自动写入 Cookie (`sdp_user_token`)
* 受保护接口会在执行前自动解析 Token 并注入 `kratos.Token` 对象

---

## 💥 错误与响应格式

### ✅ 成功响应

```json
{
  "code": 0,
  "msg": "OK",
  "data": { "token": "xxx" },
  "response_id": "66e8f...",
  "create_at": "2025-10-14T12:34:56+08:00"
}
```

### ❌ 错误响应

```json
{
  "code": 3,
  "msg": "多层错误测试",
  "error": "写入日志失败 <- 数据解析错误 <- DB连接失败"
}
```

---

## ⚙️ 事务支持

只需在 `router.xml` 设置：

```xml
<Transcation>true</Transcation>
```

框架自动为该接口启用 MongoDB 事务，失败自动回滚。

---

## 📦 文件上传

使用 `kratos.GetFormFile(ctx, "file")` 获取文件：

```go
file, header, err := kratos.GetFormFile(ctx, "file")
```

文件保存示例：

```go
path := "./uploads/" + header.Filename
out, _ := os.Create(path)
io.Copy(out, file)
```

---

## 🧠 开发模板（推荐）

```go
func (s *Serv) FunctionName(ctx context.Context, token kratos.Token, body []byte, query map[string]string) (interface{}, error) {
    // 1. 参数解析
    // 2. 业务逻辑
    // 3. 错误封装
    // 4. 返回数据
    return bson.M{"ok": true}, nil
}
```

在 `router.xml` 中注册：

```xml
<Route>
  <Method>function.name</Method>
  <Name>FunctionName</Name>
  <Transcation>false</Transcation>
  <Authorization>true</Authorization>
</Route>
```

---

## 🧾 响应封装逻辑

框架统一响应结构：

| 字段            | 含义           |
| ------------- | ------------ |
| `code`        | 状态码（0 成功）    |
| `msg`         | 信息提示         |
| `data`        | 返回数据         |
| `response_id` | 响应唯一 ID      |
| `create_at`   | 时间戳          |
| `error`       | 错误堆栈信息（仅错误时） |

---

## 💡 建议与扩展

| 功能   | 建议                            |
| ---- | ----------------------------- |
| 日志记录 | 结合 `kratos.Error.Log()` 输出到文件 |
| 存储扩展 | 文件上传支持 OSS / MinIO            |
| 权限控制 | 在 `GetToken()` 中扩展角色字段        |
| 接口文档 | 可自动解析 `router.xml` 生成 Swagger |

---

## 🧱 License

MIT License © 2025 Cuiyunfeng

---

> 💬 “Kratos 框架让业务开发只关注逻辑，
> 不再被路由、事务、鉴权、错误困扰。”