2. 环境搭建：Go 1.21+ 开发环境配置、gin框架初始化、项目目录结构设计

本章将搭建完整的 Go Web 授权测试实验环境。环境基于 Go 1.21+ 标准工具链，使用 gin 框架作为 HTTP 服务核心，并按照“授权测试”的工程需求设计项目目录结构。完成本章配置后，你将拥有一个可直接运行 Token 自省与撤销端点测试的本地开发环境。

2.1 开发环境要求与版本确认

本课程所有实验均基于 Go 1.21 及以上版本。Go 1.21 引入了 log/slog 结构化日志、maps 和 slices 标准包增强，以及更严格的泛型类型推断，这些特性在后续的 Token 验证中间件和测试代码中会被直接使用。

组件 最低版本 推荐版本 用途
Go 1.21 1.22.5 编译运行、标准库测试
gin v1.9.1 v1.10.0 HTTP 路由、中间件链
go-jose v3.0.3 v4.0.1 JWT 签名与验证
testify v1.8.4 v1.9.0 断言与 mock 辅助
版本检查命令： 在终端执行 go version 确认 Go 版本。若低于 1.21，请从 https://go.dev/dl/ 下载对应操作系统的安装包进行升级。

2.2 项目初始化与模块管理

使用 Go Modules 管理依赖。在项目根目录下执行以下命令完成初始化：

mkdir go-web-auth-testing
cd go-web-auth-testing
go mod init github.com/yourname/go-web-auth-testing
go get github.com/gin-gonic/gin@latest
go get github.com/stretchr/testify@latest
go get github.com/go-jose/go-jose/v4@latest

初始化完成后，go.mod 文件应包含以下核心依赖（版本号以实际拉取为准）：

module github.com/yourname/go-web-auth-testing

go 1.21

require (
    github.com/gin-gonic/gin v1.10.0
    github.com/go-jose/go-jose/v4 v4.0.1
    github.com/stretchr/testify v1.9.0
)
注意： 如果使用 Go 1.21 以下版本，gin v1.10.0 可能因泛型依赖无法编译。请务必确保 Go 版本 ≥ 1.21。若网络环境受限，可设置 GOPROXY=https://goproxy.cn,direct 加速依赖下载。

2.3 项目目录结构设计

针对“Token 自省与撤销端点边界验证”这一主题，目录结构按功能分层，将 HTTP 层、业务逻辑层、数据层和测试层清晰分离。以下是完整结构：

go-web-auth-testing/
├── cmd/
│   └── server/
│       └── main.go              # 应用入口，启动 HTTP 服务
├── internal/
│   ├── handler/
│   │   ├── introspection.go     # Token 自省端点处理函数
│   │   ├── revocation.go        # Token 撤销端点处理函数
│   │   └── token.go             # Token 颁发辅助端点（测试用）
│   ├── middleware/
│   │   ├── auth.go              # 认证中间件（Bearer Token 提取）
│   │   └── ratelimit.go         # 速率限制中间件（边界测试用）
│   ├── model/
│   │   ├── token.go             # Token 数据结构与状态定义
│   │   └── introspection.go     # 自省请求/响应结构体
│   ├── store/
│   │   ├── memory.go            # 内存存储实现（开发/测试用）
│   │   └── store.go             # 存储接口定义
│   └── service/
│       ├── introspection.go     # 自省业务逻辑
│       └── revocation.go        # 撤销业务逻辑
├── pkg/
│   └── jwtutil/
│       └── jwt.go               # JWT 签名、验证、解析工具函数
├── test/
│   ├── integration/
│   │   ├── introspection_test.go # 自省端点集成测试
│   │   └── revocation_test.go    # 撤销端点集成测试
│   └── fixtures/
│       └── testkeys/
│           ├── private.pem       # 测试用 RSA 私钥
│           └── public.pem        # 测试用 RSA 公钥
├── config/
│   └── config.go                # 配置加载（端口、密钥路径等）
├── go.mod
├── go.sum
└── README.md
设计要点：
  • cmd/server/main.go 保持精简，只负责启动 gin 引擎和注册路由。
  • internal/ 目录下的包不允许被外部项目导入，符合 Go 官方推荐的项目布局。
  • store/ 层定义了接口，便于后续切换为 Redis 或数据库实现，测试时使用内存存储。
  • test/fixtures/ 存放测试密钥和固定数据，避免测试依赖外部服务。

2.4 gin 框架初始化与路由注册

在 cmd/server/main.go 中完成 gin 引擎的初始化，并注册三个核心端点：Token 颁发（测试辅助）、自省、撤销。以下是完整的启动代码：

package main

import (
    "log/slog"
    "os"

    "github.com/gin-gonic/gin"
    "github.com/yourname/go-web-auth-testing/internal/handler"
    "github.com/yourname/go-web-auth-testing/internal/middleware"
    "github.com/yourname/go-web-auth-testing/internal/store"
)

func main() {
    // 初始化结构化日志
    logger := slog.New(slog.NewTextHandler(os.Stdout, nil))
    slog.SetDefault(logger)

    // 初始化内存存储（测试环境使用）
    tokenStore := store.NewMemoryStore()

    // 创建 gin 引擎，生产环境建议使用 gin.ReleaseMode
    r := gin.Default()

    // 注册全局中间件：请求日志、恢复
    r.Use(gin.Logger(), gin.Recovery())

    // 公开端点：Token 颁发（仅测试环境使用）
    r.POST("/token", handler.IssueToken(tokenStore))

    // 受保护端点组：需要 Bearer Token 认证
    authGroup := r.Group("/oauth")
    authGroup.Use(middleware.BearerAuth(tokenStore))
    {
        // Token 自省端点
        authGroup.POST("/introspect", handler.IntrospectToken(tokenStore))
        // Token 撤销端点
        authGroup.POST("/revoke", handler.RevokeToken(tokenStore))
    }

    // 启动服务，默认监听 8080 端口
    slog.Info("Starting server on :8080")
    if err := r.Run(":8080"); err != nil {
        slog.Error("Server failed to start", "error", err)
        os.Exit(1)
    }
}
中间件注册顺序说明： gin.Logger() 和 gin.Recovery() 作为全局中间件最先注册，确保所有请求都有日志和异常恢复。BearerAuth 中间件只作用于 /oauth 组，自省和撤销端点共享同一认证逻辑，便于后续统一修改认证策略。

2.5 环境验证：启动服务并测试端点

完成上述代码后，在项目根目录执行以下命令启动服务：

go run ./cmd/server/

服务启动后，使用 curl 验证三个端点是否正常响应：

# 1. 颁发一个测试 Token
curl -s -X POST http://localhost:8080/token \
  -H "Content-Type: application/json" \
  -d '{"subject":"test-user","scope":"read write"}'

# 返回示例（实际 Token 值会不同）：
# {"access_token":"eyJhbGciOiJSUzI1NiIs...","token_type":"Bearer","expires_in":3600}

# 2. 使用颁发的 Token 调用自省端点
curl -s -X POST http://localhost:8080/oauth/introspect \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{"token":"eyJhbGciOiJSUzI1NiIs..."}'

# 3. 撤销 Token
curl -s -X POST http://localhost:8080/oauth/revoke \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{"token":"eyJhbGciOiJSUzI1NiIs..."}'
边界测试提醒： 在后续章节中，我们将针对上述端点构造大量边界测试用例，包括：空 Token、过期 Token、已撤销 Token、签名错误的 Token、超长 Token、特殊字符 Token 等。当前环境搭建阶段只需确保端点能正常启动并返回 HTTP 200/401/403 即可。

2.6 项目架构总览

下图展示了本课程实验环境的整体架构，以及各组件之间的调用关系：

Go Web 授权测试环境架构图 HTTP 客户端 Gin 引擎 中间件链 路由分发 Handler Service Store 请求流向 客户端 → Gin → 中间件 → 路由 → Handler → Service → Store 测试关注点 边界输入、空值、 过期、签名错误、 并发撤销、重复自省

架构图中，请求从 HTTP 客户端进入 Gin 引擎，依次经过中间件链（认证、速率限制）、路由分发，最终到达 Handler。Handler 调用 Service 层执行业务逻辑，Service 层通过 Store 接口操作 Token 数据。每一层都是后续边界测试的切入点。

2.7 本章小结

完成本章环境搭建后，你已具备以下能力：

  • 使用 Go 1.21+ 和 gin 框架搭建了可运行的 Web 服务骨架。
  • 按照授权测试需求设计了分层清晰的项目目录结构。
  • 注册了 Token 颁发、自省、撤销三个核心端点，并配置了认证中间件。
  • 通过 curl 验证了服务端点的基本可用性。
← 上一章 📖 返回目录 下一章 →