09 Go Eino AI应用开发实战 | Hertz Web 框架搭建

声明：本AI应用开发系列教程首发在同名公众号：王中阳，未经授权禁止转载。

Hertz Web 框架作为 AI Interview Agent 平台的核心支柱，提供高性能的 HTTP 路由、中间件编排和请求处理能力。本指南涵盖 Hertz 在项目架构中的完整设置和配置。

框架初始化

Hertz 服务器在主应用程序入口点初始化，通过包含配置加载、数据库连接和中间件注册的完整设置序列 [main.go#L101-L175]。

服务器初始化遵循以下关键模式：

go 复制代码

// 使用配置中的主机和端口初始化 Hertz 服务器
s := server.Default(server.WithHostPorts(fmt.Sprintf("%s:%d", cfg.Host, cfg.Port)))

中间件架构

Hertz 实现了分层中间件架构来处理横切关注点：

恢复中间件

恢复中间件捕获 panic 并防止服务器崩溃，提供结构化错误响应 [recovery.go#L15-L35]：

go 复制代码

func Recovery() app.HandlerFunc {
    return func(ctx context.Context, c *app.RequestContext) {
        defer func() {
            if r := recover(); r != nil {
                stack := debug.Stack()
                log.Printf("[PANIC] Recovered: %v\n%s", r, stack)
                // 返回结构化错误响应
            }
        }()
        c.Next(ctx)
    }
}

CORS 配置

全局 CORS 中间件通过全面的头部配置处理跨域请求 [main.go#L113-L127]：

Header	Value	Purpose
Access-Control-Allow-Origin	*	允许所有来源
Access-Control-Allow-Methods	GET, POST, PUT, DELETE, OPTIONS	允许的 HTTP 方法
Access-Control-Allow-Headers	Content-Type, Authorization, X-Requested-With, Cache-Control, X-Auth-Token	允许的请求头
Access-Control-Max-Age	86400	预检请求缓存 24 小时

JWT 认证

JWT 中间件提供基于令牌的认证，支持可配置的路由跳过 [jwt.go#L37-L79]。绕过认证的公共路由包括：

/api/user/login
/api/user/register
/api/user/logout
/api/user/wechat/login
/api/user/wechat/callback
/api/demo/create/model

路由注册系统

Hertz 使用基于 IDL 定义的自动生成路由注册系统 [register.go#L11-L16]。路由层次遵循结构化模式：

bash 复制代码

/
├── /api/
    ├── /interview/
    │   ├── /records (GET)
    │   └── /stream/
    │       └── /start (POST)
    ├── /mianshi/
    │   ├── /answer-record (GET)
    │   ├── /evaluation (GET)
    │   ├── /records (GET)
    │   ├── /answer/
    │   │   └── /submit (POST)
    │   ├── /interview/
    │   │   └── /end (POST)
    │   ├── /session/
    │   │   └── /info (GET)
    │   └── /stream/
    │       └── /start (POST)
    ├── /prediction/
    │   ├── /:id (GET)
    │   ├── /list (GET)
    │   └── /start (POST)
    ├── /resume/
    │   ├── /default (GET)
    │   ├── /list (GET)
    │   ├── /:resume_id (GET, PUT, DELETE)
    │   ├── /set-default (POST)
    │   └── /upload (POST)
    └── /user/
        ├── /login (POST)
        ├── /register (POST)
        ├── /profile (GET, PUT)
        ├── /create/model (POST)
        ├── /model/
        │   ├── /check (GET)
        │   ├── /list (GET)
        │   ├── /delete/:id (DELETE)
        │   ├── /details/:id (GET)
        │   └── /update/:id (PUT)
        └── /wechat/
            ├── /login (GET)
            └── /callback (GET)

路由注册是使用 Hertz 生成器从 IDL 定义自动生成的。手动修改生成的文件将在更新时被覆盖。

配置集成

Hertz 配置与应用程序的集中式配置系统集成 [config.go#L75-L83]：

go 复制代码

type HertzConfig struct {
    Host         string        `yaml:"host"`
    Port         int           `yaml:"port"`
    ReadTimeout  time.Duration `yaml:"read_timeout"`
    WriteTimeout time.Duration `yaml:"write_timeout"`
    IdleTimeout  time.Duration `yaml:"idle_timeout"`
}

服务器使用环境变量扩展，允许通过 YAML 文件中的 ${VAR_NAME} 语法进行灵活配置。

优雅关闭

Hertz 实现了带有适当资源清理的优雅关闭 [main.go#L147-L175]：

信号处理：监听 SIGINT 和 SIGTERM 信号
消费者关闭：停止消息队列消费者
队列清理：关闭消息队列连接
服务器关闭：在 5 秒超时内优雅关闭 HTTP 连接

优雅关闭序列确保所有进行中的请求完成，同时阻止新请求，在重启期间维护数据完整性。

性能考虑

Hertz 设置包括多项性能优化：

连接池：通过数据库和 Redis 连接设置配置
请求超时：可配置的读取、写入和空闲超时防止资源泄漏
中间件顺序：关键中间件（恢复、CORS）置于认证之前以获得最佳性能
静态文件处理：通过 Hertz 内置的静态文件功能高效提供

集成点

Hertz 与其他系统组件无缝集成：

消息队列：基于 Redis 的异步处理队列
数据库：GORM 集成用于数据持久化
AI 服务：Eino 框架集成用于 AI Agent 编排
文件存储：简历上传和管理能力

框架的模块化设计允许轻松扩展和维护，同时为 AI Interview Agent 平台保持高性能和可靠性。