# go-tpl

**Repository Path**: httpadmin/go-tpl

## Basic Information

- **Project Name**: go-tpl
- **Description**: 一个面向业务项目起步的 Gin 后端模板。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-29
- **Last Updated**: 2026-04-02

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Go Backend Template

一个面向业务项目起步的 Gin 后端模板。

模板默认包含 4 个对外模块：
- `admin`：管理后台接口，内置登录与 RBAC 基础结构
- `console`：客户控制台接口
- `api`：客户端接口
- `web`：官网或公开页面接口

模板默认包含 2 个对内模块：
- `config`：动态配置能力，由 `admin` 管理，供 `admin/console/api/web` 读取
- `whitelist`：白名单能力预留骨架，后续可继续实现

## 技术栈

- Go 1.22
- Gin
- Viper
- Zap
- AES-GCM Token

## 目录规划


模块内建议继续保持如下pkg的内聚：
- `service`
- `repository`
- `model`

## 已内置能力

- 静态配置加载
- 动态配置管理
- 统一响应结构，响应值已在 `pkg/resp/resp.go` 中封装
- `traceId` 注入与日志透传
- 分模块独立 Token 鉴权
- `admin` RBAC 基础结构
- `worker` 入口骨架
- 微信、OSS、AI、Redis 队列占位适配器

## 鉴权设计

- `admin`、`console`、`api` 各自独立 Token 配置
- `admin` 模块保留角色与权限字段结构
- `console` 与 `api` 的 token 不共享
- 项目认证并非使用 JWT，也不建议接入 JWT
- 默认使用项目内封装的 Token 机制，具体实现可参考 `internal/support/tokenx/token.go`
- 当前 token 中间件只校验 token 是否有效，并解析 payload 信息，不负责角色或权限校验

接口返回建议直接复用 `pkg/resp/resp.go` 中的统一响应封装：

- `resp.OK(c, data)`：返回成功响应
- `resp.Fail(c, code)`：按错误码返回默认失败文案
- `resp.FailWithMsg(c, code, msg)`：返回带自定义文案的失败响应
- `resp.FailWithData(c, code, msg, data)`：返回带自定义文案和数据的失败响应

## 启动

本地开发使用：

```bash
go run ./cmd/api --env test
```

示例账号：
- `admin / admin123`
- `console / console123`

示例接口：
- `POST /admin/auth/login`
- `POST /console/auth/login`
- `POST /api/auth/demo-login`
- `GET /web/health`

## 配置

配置文件位于：
- `etc/config.tpl.yaml`
- `etc/config.test.yaml`
- `etc/config.prod.yaml`

默认保留以下通用配置分组：
- `app`
- `server`
- `log`
- `cors`
- `auth`
- `mysql`
- `redis`
- `oss`
- `wechat`
- `ai`
- `queue`
- `storage`

## 新项目使用建议

1. 修改 `go.mod` 的模块名
2. 替换 `app.name`
3. 按业务继续扩展 `internal/module/*`
4. 将内存仓储替换为 MySQL、Redis 等真实实现
5. 按项目需要补充 `config` 与 `whitelist` 的真实存储与管理接口