# auth-service

**Repository Path**: seemswork/auth-service

## Basic Information

- **Project Name**: auth-service
- **Description**: 鉴权服务
- **Primary Language**: Go
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-19
- **Last Updated**: 2026-01-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Auth Service 鉴权服务

基于 Go 官方库实现的轻量级鉴权服务，借鉴微信小程序登录鉴权逻辑，采用分层架构设计，支持用户登录、Token 验证、登出等核心功能，适配 PostgreSQL 数据库，无第三方 Web 框架依赖。

## 核心功能

- **用户登录**：通过临时凭证 Code 换取自定义 Token
- **接口鉴权**：基于 Token 验证用户身份，保护需要登录的接口
- **用户登出**：使当前 Token 失效，终止登录态
- **Token 自动过期**：默认 7 天有效期，过期自动失效

## 设计亮点

- **安全可靠**：SessionKey 全程存储在服务端，前端仅持有 Token，避免敏感信息泄露
- **轻量级**：仅依赖 PostgreSQL 官方驱动，无第三方 Web 框架
- **分层架构**：清晰的分层设计，便于维护和扩展

## 技术栈

- **开发语言**：Go 1.18+
- **数据库**：PostgreSQL 12+
- **依赖包**：github.com/lib/pq（PostgreSQL 官方兼容驱动）
- **通信协议**：HTTP

## 快速开始

### 环境准备

1. 安装 Go 1.18+（参考 [Go 官方安装指南](https://go.dev/dl/)）
2. 安装 PostgreSQL 12+（参考 [PostgreSQL 官方下载页](https://www.postgresql.org/download/)）
3. 创建数据库：`CREATE DATABASE auth_db;`

### 数据库初始化

```sql
-- 1. 业务方表（接入鉴权服务的应用，如APP、前端、小程序）
CREATE TABLE IF NOT EXISTS auth_app (
    id SERIAL PRIMARY KEY,
    appid VARCHAR(64) NOT NULL UNIQUE,        -- 业务方唯一标识（自主分配）
    appsecret VARCHAR(128) NOT NULL,          -- 业务方密钥（签名用）
    app_name VARCHAR(128) NOT NULL,           -- 业务方名称
    is_enabled BOOLEAN DEFAULT TRUE,          -- 是否启用
    created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP
);


-- 2. 用户鉴权表（存储SessionKey等核心信息）
CREATE TABLE IF NOT EXISTS user_auth (
    id SERIAL PRIMARY KEY,
    appid VARCHAR(64) NOT NULL REFERENCES auth_app(appid), -- 关联业务方
    user_id VARCHAR(64) NOT NULL,             -- 业务方用户唯一标识（自主定义）
    session_key VARCHAR(128) NOT NULL,        -- 自主生成的会话密钥
    session_key_expires_at TIMESTAMP WITH TIME ZONE NOT NULL, -- SessionKey过期时间（2小时）
    is_valid BOOLEAN DEFAULT TRUE,            -- 是否有效
    created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
    UNIQUE(appid, user_id)                    -- 一个业务方下用户唯一
);


-- 3. Token存储表
CREATE TABLE IF NOT EXISTS token_store (
    id SERIAL PRIMARY KEY,
    token VARCHAR(128) NOT NULL UNIQUE,       -- 自主生成的业务Token
    appid VARCHAR(64) NOT NULL REFERENCES auth_app(appid),
    user_id VARCHAR(64) NOT NULL,
    expires_at TIMESTAMP WITH TIME ZONE NOT NULL, -- Token过期时间（7天）
    is_valid BOOLEAN DEFAULT TRUE,
    created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP
);

-- 4. Code存储表（一次性凭证）
CREATE TABLE IF NOT EXISTS code_record (
    id SERIAL PRIMARY KEY,
    code VARCHAR(64) NOT NULL UNIQUE,         -- 一次性Code
    appid VARCHAR(64) NOT NULL REFERENCES auth_app(appid),
    user_id VARCHAR(64) NOT NULL,
    is_used BOOLEAN DEFAULT FALSE,            -- 一次性使用标记
    expires_at TIMESTAMP WITH TIME ZONE NOT NULL, -- Code过期时间（5分钟）
    created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
    used_at TIMESTAMP WITH TIME ZONE          -- 验证时间
);

-- 索引优化
CREATE INDEX idx_user_auth_appid_userid ON user_auth(appid, user_id);
CREATE INDEX idx_token_store_token ON token_store(token);
CREATE INDEX idx_code_record_code ON code_record(code);
```

### 启动服务

```bash
# 初始化 Go 模块
go mod init auth-service

# 安装 PostgreSQL 驱动
go get github.com/lib/pq

# 配置数据库连接（环境变量）
export PG_HOST=localhost
export PG_PORT=5432
export PG_USER=postgres
export PG_PASSWORD=你的密码
export PG_DBNAME=auth_db

# 启动服务
go run cmd/main.go
```

服务启动成功后会监听 8080 端口。

## 接口文档

所有接口均使用 JSON 格式。

### 1. 登录接口

- **接口地址**：`/api/login`
- **请求方法**：POST
- **鉴权**：否

**请求体：**

```json
{
  "code": "test_code_123"
}
```

**成功响应（200）：**

```json
{
  "token": "f8e7d6c5b4a392817069584736251401f8e7d6c5b4a392817069584736251401",
  "expires_at": 1740000000
}
```

**错误响应（401）：**

```json
"code 不能为空"
```

### 2. 测试接口

- **接口地址**：`/api/test`
- **请求方法**：GET
- **鉴权**：是

**请求头：**

```
Authorization: Bearer <token>
```

**成功响应（200）：**

```json
{
  "openid": "9876543210abcdef9876543210abcdef",
  "message": "鉴权成功，这是需要登录才能访问的接口"
}
```

**错误响应（401）：**

```json
"Token 已过期"
```

### 3. 登出接口

- **接口地址**：`/api/logout`
- **请求方法**：POST
- **鉴权**：是

**请求头：**

```
Authorization: Bearer <token>
```

**成功响应（200）：**

```json
{
  "message": "登出成功"
}
```

## 扩展指南

### 对接真实登录服务

修改 `internal/app/auth_service.go` 中的 `code2Session` 方法，将模拟逻辑替换为实际的服务调用：

```go
func (s *authService) code2Session(code string) (openID, sessionKey string, err error) {
    if code == "" {
        return "", "", fmt.Errorf("app: code 不能为空")
    }
    // 调用第三方接口验证 Code
    resp, err := http.Post("https://第三方服务地址/code2session", "application/json", strings.NewReader(`{"code":"`+code+`"}`))
    // 解析响应获取 realOpenID 和 realSessionKey
    return realOpenID, realSessionKey, nil
}
```

### 调整 Token 有效期

修改 `internal/domain/token.go` 中的有效期配置：

```go
// 原配置：7 天有效期
const TokenExpireDuration = 7 * 24 * time.Hour

// 修改为 2 小时有效期
const TokenExpireDuration = 2 * time.Hour
```

### 新增业务接口

1. 在 `internal/api/handler.go` 中添加新的处理器方法
2. 在 `internal/api/router.go` 中注册路由
3. 使用 `authMiddleware` 保护需要鉴权的接口
4. 业务逻辑实现在 `internal/app/auth_service.go` 中

## 项目结构

```
├── auth-service/             # 核心鉴权服务
│   ├── cmd/
│   │   └── main.go           # 鉴权服务启动入口
│   ├── config/
│   │   └── config.go         # 配置加载（数据库、有效期等）
│   ├── internal/
│   │   ├── api/
│   │   │   ├── handler.go    # HTTP接口处理器（三大核心接口）
│   │   │   ├── middleware.go # Token鉴权中间件（业务接口用）
│   │   │   └── router.go     # 路由注册
│   │   ├── app/
│   │   │   └── auth_service.go # 应用层：核心业务逻辑
│   │   ├── domain/
│   │   │   ├── app.go        # 业务方领域模型
│   │   │   ├── code.go       # Code领域模型
│   │   │   ├── token.go      # Token领域模型
│   │   │   └── user.go       # 用户领域模型
│   │   └── repo/
│   │       ├── app_repo.go   # 业务方数据操作
│   │       ├── code_repo.go  # Code数据操作
│   │       ├── db.go         # 数据库连接管理
│   │       ├── token_repo.go # Token数据操作
│   │       └── user_repo.go  # 用户数据操作
│   └── go.mod                # 鉴权服务依赖
├── code-center/              # Code中心服务（独立部署）
│   ├── cmd/
│   │   └── main.go           # Code中心启动入口
│   ├── config/
│   │   └── config.go         # Code中心配置
│   ├── internal/
│   │   ├── api/
│   │   │   ├── handler.go    # Code生成/验证接口
│   │   │   ├── middleware.go # 限流/签名中间件
│   │   │   └── router.go     # Code中心路由
│   │   ├── domain/
│   │   │   ├── app.go        # 业务方模型
│   │   │   └── code.go       # Code模型+生成规则
│   │   ├── repo/
│   │   │   ├── app_repo.go   # 业务方数据操作
│   │   │   ├── code_repo.go  # Code数据操作
│   │   │   └── db.go         # 数据库连接
│   │   └── service/
│   │       ├── app_service.go # 业务方校验逻辑
│   │       └── code_service.go # Code生成/验证逻辑
│   └── go.mod                # Code中心依赖
└── README.md                 # 整体说明文档
```

## 常见问题

**Q: 数据库连接失败？**
A: 检查环境变量配置是否正确，确认 PostgreSQL 服务已启动。

**Q: Token 验证失败？**
A: 确认请求头格式为 `Authorization: Bearer <token>`，检查 Token 是否过期。

**Q: 服务启动端口被占用？**
A: 修改 `cmd/main.go` 中的端口配置，如 `Addr: ":8080"` 改为其他端口。

## 贡献指南

- **代码规范**：使用 `go fmt` 格式化代码
- **问题反馈**：提交 Issue 或联系开发者
- **测试建议**：为核心逻辑编写单元测试

## 许可证

本项目遵循开源协议。