# goservice

**Repository Path**: lambdang/goservice

## Basic Information

- **Project Name**: goservice
- **Description**: admin框架，包括用户管理，权限管理，RGBA权限，后端基于gin，前端基于Vue Naive Admin
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-06-05
- **Last Updated**: 2026-07-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Go Service

一个基于 Gin + GORM 的轻量级后端服务框架，内置权限验证、指标监控和完整的用户管理功能。

## 特性

- **权限验证**：基于 Casbin + JWT 的 RBAC 权限控制体系
- **指标监控**：使用 expvar + 日志方式实现运行时指标监控
- **零外部基础设施依赖**：SQLite 数据库 + freecache 本地缓存，开箱即用
- **RESTful API**：完整的 CRUD 接口设计
- **自动 API 文档**：集成 Rapidoc 自动生成 API 文档

## 技术栈

- **框架**: Gin
- **ORM**: GORM
- **数据库**: SQLite
- **缓存**: freecache (通过 kvcache 封装)
- **权限**: Casbin + JWT
- **日志**: Zap
- **指标**: expvar

## 快速开始

### 环境要求

- Go 1.20+

### 启动命令

```bash
# 开发模式
cd dev && go run ../cmd/service/main.go

# 构建
go build -o service cmd/service/main.go
./service
```

服务启动后访问：
- API 服务: http://127.0.0.1:8000
- API 文档: http://127.0.0.1:8000/doc
- 指标监控: http://127.0.0.1:8000/debug/vars

## 目录结构

```
go-service/
├── cmd/service/          # 入口文件
├── dev/                  # 开发环境配置
├── internal/
│   ├── apiservice/       # API 服务层
│   │   ├── app/          # 业务模块
│   │   │   ├── admin/    # 管理员管理
│   │   │   ├── auth/     # 权限管理
│   │   │   ├── role/     # 角色管理
│   │   │   ├── me/       # 用户中心
│   │   │   └── manage/   # 系统管理
│   │   ├── middler/      # 中间件
│   │   └── router/       # 路由
│   ├── appctx/           # 应用上下文
│   ├── bootstrap/        # 启动引导
│   └── config/           # 配置管理
├── pkg/                  # 公共包
│   ├── kvcache/          # 本地缓存 (freecache)
│   ├── jwtx/             # JWT 工具
│   ├── gormx/            # GORM 扩展
│   └── zaplog/           # 日志工具
└── web/                  # 前端项目
```

## 权限验证

### RBAC 模型

框架使用 Casbin 实现 RBAC 权限控制：

```
[request_definition]
r = role, api, method

[policy_definition]
p = role, api, method

[matchers]
m = r.role == p.role && keyMatch2(r.api,p.api) && r.method==p.method
```

### 权限校验流程

1. 用户登录获取 JWT Token
2. 请求携带 Token 通过 `token` 中间件验证
3. `check_auth` 中间件通过 Casbin 校验角色权限
4. 权限不足返回 403 错误

## 指标监控

### expvar 指标

访问 `/debug/vars` 获取实时运行指标：

- `goroutines` - 当前 Goroutine 数量
- `threads` - CPU 线程数
- `start_time` - 服务启动时间
- `kv_cache_count` - 缓存条目数
- `kv_cache_eviction_count` - 缓存淘汰次数

### 日志监控

所有请求通过 `httplog` 中间件记录访问日志，包含请求路径、方法、耗时、状态码等信息。

## 配置说明

配置文件位于 `dev/config.yaml`：

```yaml
user: admin                    # 默认管理员账号
password: adminpassword        # 默认管理员密码
isDev: true                    # 开发模式
root: ./                       # 工作目录
sqlite: goservice.db           # SQLite 数据库文件

api:
  host: 127.0.0.1:8000         # API 服务地址
  jwtSecret: your-secret-key   # JWT 密钥
  jwtExp: 3600                 # JWT 过期时间(秒)

kvCache:
  sizeM: 5                     # 缓存大小(MB)
  ttlS: 30                     # 默认过期时间(秒)
```

## API 模块

| 模块 | 路径 | 说明 |
|------|------|------|
| 用户中心 | `/api/me/*` | 登录、退出、个人信息 |
| 管理员 | `/api/admin/*` | 管理员增删改查 |
| 角色 | `/api/role/*` | 角色管理、权限分配 |
| 权限 | `/api/auth/*` | 权限定义管理 |
| 系统管理 | `/api/manage/*` | 系统配置管理 |

## 默认账号

- **账号**: admin
- **密码**: adminpassword

## 缓存机制

框架使用 `kvcache`（基于 freecache）作为本地缓存：

- 无外部依赖，进程内缓存
- 使用 MessagePack 序列化数据
- 支持自动淘汰策略
- 缓存条目数和淘汰次数可监控

## 前端项目

前端项目位于 `web/` 目录，使用 Vue + Vite 构建：

```bash
cd web
npm install
npm run dev
```

生产环境构建：

```bash
npm run build
```

构建产物输出到 `web/dist/`，后端会自动托管该目录下的静态文件。