mirror of
https://github.com/Rain-kl/OpenFlare.git
synced 2026-09-28 21:56:36 +08:00
Compare commits
51 Commits
| Author | SHA1 | Date | |
|---|---|---|---|
 ryan
|
f960511cc0 | ||
|
ryan
|
465440fa5b | ||
|
ryan
|
a4dd5ca9e1 | ||
|
ryan
|
a9e4237bbf | ||
|
ryan
|
75d1fcf345 | ||
|
ryan
|
f1577bf092 | ||
|
ryan
|
01ed2c5e36 | ||
|
ryan
|
80696c12fa | ||
|
ryan
|
3d4d99081e | ||
|
ryan
|
0639855653 | ||
|
ryan
|
0524ae1da4 | ||
|
ryan
|
adee4f7b27 | ||
|
ryan
|
1d0f2d6342 | ||
|
ryan
|
e3f603f72a | ||
|
ryan
|
3b010bb15e | ||
|
ryan
|
f530cd4025 | ||
|
ryan
|
08d28c2c8e | ||
|
ryan
|
34a0896ff8 | ||
|
ryan
|
0c22e76f4b | ||
|
ryan
|
bd2183c8bb | ||
|
ryan
|
9df2437e47 | ||
|
ryan
|
e8c414aa12 | ||
|
ryan
|
7e8aa5fa0f | ||
|
ryan
|
7e518987de | ||
|
ryan
|
61484090f9 | ||
|
ryan
|
94b74d72f6 | ||
|
ryan
|
6487ce666d | ||
|
ryan
|
c4be34b214 | ||
|
ryan
|
fda727cf53 | ||
|
ryan
|
f083da20f2 | ||
|
ryan
|
9797fcdb2f | ||
|
Ryan
|
93ec3096f3 | ||
|
Ryan
|
0e34301c92 | ||
|
Ryan
|
12b5271f92 | ||
|
Ryan
|
8ee966434d | ||
|
ryan
|
6882481a56 | ||
|
ryan
|
b675038bba | ||
|
ryan
|
d17ec9d17d | ||
|
ryan
|
8758f9a061 | ||
|
ryan
|
7d93d3d2a1 | ||
|
Ryan
|
074edf17a1 | ||
|
Ryan
|
6faf525af0 | ||
|
ryan
|
a6fc2b7737 | ||
|
ryan
|
ca21ff3a5b | ||
|
ryan
|
7d71f1e4e1 | ||
|
ryan
|
734fe45baa | ||
|
ryan
|
ef22ecc5dc | ||
|
ryan
|
6738abdec1 | ||
|
ryan
|
d17d8457f3 | ||
|
ryan
|
16f34928c9 | ||
|
ryan
|
3328d3d121 |
@@ -1,183 +0,0 @@
|
||||
---
|
||||
name: go-code-review
|
||||
description: Use when reviewing Go code or checking code against community style standards. Also use proactively before submitting a Go PR or when reviewing any Go code changes, even if the user doesn't explicitly request a style review. Does not cover language-specific syntax — delegates to specialized skills.
|
||||
license: Apache-2.0
|
||||
compatibility: Web server example in references uses slog (Go 1.21+)
|
||||
metadata:
|
||||
sources: "Go Wiki CodeReviewComments, Uber Style Guide"
|
||||
allowed-tools: Bash(bash:*)
|
||||
---
|
||||
|
||||
# Go 代码审查清单
|
||||
|
||||
## 审查流程
|
||||
|
||||
> 使用 `assets/review-template.md` 格式化代码审查输出，确保结构与"必须修复 / 建议修复 / 吹毛求疵"的严重程度分组保持一致。
|
||||
|
||||
1. 运行 `gofmt -d .` 和 `go vet ./...` 先捕获机械性问题
|
||||
2. 逐文件阅读 diff；对于每个文件，按以下类别顺序检查
|
||||
3. 标记问题时需要包含具体行号引用和规则名称
|
||||
4. 审查完所有文件后，重新阅读标记项以确认它们是真实的问题
|
||||
5. 按严重程度分组汇总发现（必须修复、建议修复、吹毛求疵）
|
||||
|
||||
> **验证**：完成审查后，再次阅读 diff 以验证每个标记的问题都是真实的。删除任何无法用具体行号引用的发现。
|
||||
|
||||
---
|
||||
|
||||
## 格式化
|
||||
|
||||
- [ ] **gofmt**：代码已使用 `gofmt` 或 `goimports` 格式化 → [go-linting](../go-linting/SKILL.md)
|
||||
|
||||
---
|
||||
|
||||
## 文档
|
||||
|
||||
- [ ] **注释句子**：注释是完整的句子，以被描述的名称开头，以句号结尾 → [go-documentation](../go-documentation/SKILL.md)
|
||||
- [ ] **文档注释**：所有导出名称都有文档注释；非平凡的未导出声明也应有 → [go-documentation](../go-documentation/SKILL.md)
|
||||
- [ ] **包注释**：包注释出现在 package 子句附近，无空行 → [go-documentation](../go-documentation/SKILL.md)
|
||||
- [ ] **命名结果参数**：仅当它们能澄清含义时使用（例如，多个相同类型返回值），而不仅仅是为了启用裸返回 → [go-documentation](../go-documentation/SKILL.md)
|
||||
|
||||
---
|
||||
|
||||
## 错误处理
|
||||
|
||||
- [ ] **处理错误**：不使用 `_` 丢弃错误；处理、返回或（在特殊情况下）panic → [go-error-handling](../go-error-handling/SKILL.md)
|
||||
- [ ] **错误字符串**：小写开头，无标点（除非以专有名词/首字母缩略词开头） → [go-error-handling](../go-error-handling/SKILL.md)
|
||||
- [ ] **带内错误**：不使用魔术值（-1、""、nil）；使用带 error 或 ok bool 的多返回值 → [go-error-handling](../go-error-handling/SKILL.md)
|
||||
- [ ] **错误流缩进**：先处理错误并返回；保持正常路径的缩进最小化 → [go-error-handling](../go-error-handling/SKILL.md)
|
||||
|
||||
---
|
||||
|
||||
## 命名
|
||||
|
||||
- [ ] **MixedCaps**：使用 `MixedCaps` 或 `mixedCaps`，不使用下划线；未导出使用 `maxLength` 而非 `MAX_LENGTH` → [go-naming](../go-naming/SKILL.md)
|
||||
- [ ] **首字母缩略词**：保持一致的大小写：`URL`/`url`、`ID`/`id`、`HTTP`/`http`（例如 `ServeHTTP`、`xmlHTTPRequest`） → [go-naming](../go-naming/SKILL.md)
|
||||
- [ ] **变量名**：有限作用域用短名称（`i`、`r`、`c`）；更广作用域用较长名称 → [go-naming](../go-naming/SKILL.md)
|
||||
- [ ] **接收器名称**：类型的一两个字母缩写（`c` 代表 `Client`）；不使用 `this`、`self`、`me`；各方法之间保持一致 → [go-naming](../go-naming/SKILL.md)
|
||||
- [ ] **包名**：不重复（使用 `chubby.File` 而非 `chubby.ChubbyFile`）；避免 `util`、`common`、`misc` → [go-packages](../go-packages/SKILL.md)
|
||||
- [ ] **避免内置名称**：不遮蔽 `error`、`string`、`len`、`cap`、`append`、`copy`、`new`、`make` → [go-declarations](../go-declarations/SKILL.md)
|
||||
|
||||
---
|
||||
|
||||
## 并发
|
||||
|
||||
- [ ] **Goroutine 生命周期**：明确 goroutine 何时/是否退出；如不明显则添加文档 → [go-concurrency](../go-concurrency/SKILL.md)
|
||||
- [ ] **同步函数**：优先同步而非异步；让调用者在需要时添加并发 → [go-concurrency](../go-concurrency/SKILL.md)
|
||||
- [ ] **Context**：作为第一个参数；不放在 struct 中；不自定义 Context 类型；即使认为不需要也应传递 → [go-context](../go-context/SKILL.md)
|
||||
|
||||
---
|
||||
|
||||
## 接口
|
||||
|
||||
- [ ] **接口位置**：在消费方包中定义，而非实现方；生产者返回具体类型 → [go-interfaces](../go-interfaces/SKILL.md)
|
||||
- [ ] **不提前定义接口**：不在使用前定义；不在实现方"为了 mock"而定义 → [go-interfaces](../go-interfaces/SKILL.md)
|
||||
- [ ] **接收器类型**：如果会修改状态、有 sync 字段或体积大，使用指针；小的不可变类型使用值；不要混用 → [go-interfaces](../go-interfaces/SKILL.md)
|
||||
|
||||
---
|
||||
|
||||
## 数据结构
|
||||
|
||||
- [ ] **空切片**：优先使用 `var t []string`（nil）而非 `t := []string{}`（非 nil 零长度） → [go-data-structures](../go-data-structures/SKILL.md)
|
||||
- [ ] **复制**：小心复制含指针/切片字段的结构体；不按值复制 `*T` 方法的接收器 → [go-data-structures](../go-data-structures/SKILL.md)
|
||||
|
||||
---
|
||||
|
||||
## 安全性
|
||||
|
||||
- [ ] **加密随机数**：密钥使用 `crypto/rand`，不使用 `math/rand` → [go-defensive](../go-defensive/SKILL.md)
|
||||
- [ ] **不 panic**：常规错误处理使用 error 返回；仅在真正特殊的情况下 panic → [go-defensive](../go-defensive/SKILL.md)
|
||||
|
||||
---
|
||||
|
||||
## 声明与初始化
|
||||
|
||||
- [ ] **分组相似的**：相关的 `var`/`const`/`type` 放在括号块中；不相关的分开 → [go-declarations](../go-declarations/SKILL.md)
|
||||
- [ ] **var vs :=**：有意使用零值时用 `var`；显式赋值时用 `:=` → [go-declarations](../go-declarations/SKILL.md)
|
||||
- [ ] **缩小作用域**：将声明移到使用位置附近；使用 if-init 限制变量作用域 → [go-declarations](../go-declarations/SKILL.md)
|
||||
- [ ] **Struct 初始化**：始终使用字段名；省略零值字段；零值 struct 使用 `var` → [go-declarations](../go-declarations/SKILL.md)
|
||||
- [ ] **使用 `any`**：新代码中优先使用 `any` 而非 `interface{}` → [go-declarations](../go-declarations/SKILL.md)
|
||||
|
||||
---
|
||||
|
||||
## 函数
|
||||
|
||||
- [ ] **文件排序**：类型 → 构造函数 → 导出方法 → 未导出方法 → 工具函数 → [go-functions](../go-functions/SKILL.md)
|
||||
- [ ] **签名格式化**：换行时所有参数各占一行并带尾逗号 → [go-functions](../go-functions/SKILL.md)
|
||||
- [ ] **裸参数**：为含义不明确的 bool/int 参数添加 `/* name */` 注释，或使用自定义类型 → [go-functions](../go-functions/SKILL.md)
|
||||
- [ ] **Printf 命名**：接受格式字符串的函数以 `f` 结尾，以便 `go vet` 检查 → [go-functions](../go-functions/SKILL.md)
|
||||
|
||||
---
|
||||
|
||||
## 风格
|
||||
|
||||
- [ ] **行长度**：无硬性限制，但避免令人不适的长行；按语义断行，而非任意长度 → [go-style-core](../go-style-core/SKILL.md)
|
||||
- [ ] **裸返回**：仅在短函数中使用；中/大函数使用显式返回 → [go-style-core](../go-style-core/SKILL.md)
|
||||
- [ ] **传值**：不要仅为节省字节而使用指针；小的固定大小类型传 `string` 而非 `*string` → [go-performance](../go-performance/SKILL.md)
|
||||
- [ ] **字符串拼接**：简单拼接用 `+`；格式化用 `fmt.Sprintf`；循环中用 `strings.Builder` → [go-performance](../go-performance/SKILL.md)
|
||||
|
||||
---
|
||||
|
||||
## 日志
|
||||
|
||||
- [ ] **使用 slog**：新代码使用 `log/slog`，不使用 `log` 或 `fmt.Println` 进行运维日志记录 → [go-logging](../go-logging/SKILL.md)
|
||||
- [ ] **结构化字段**：日志消息使用静态字符串加键值属性，不使用 fmt.Sprintf → [go-logging](../go-logging/SKILL.md)
|
||||
- [ ] **适当的级别**：Debug 用于开发者追踪，Info 用于重要事件，Warn 用于可恢复的问题，Error 用于故障 → [go-logging](../go-logging/SKILL.md)
|
||||
- [ ] **日志中无敏感信息**：PII、凭证和令牌永远不记录在日志中 → [go-logging](../go-logging/SKILL.md)
|
||||
|
||||
---
|
||||
|
||||
## 导入
|
||||
|
||||
- [ ] **导入分组**：标准库优先，然后空行，再外部包 → [go-packages](../go-packages/SKILL.md)
|
||||
- [ ] **导入重命名**：除非冲突否则避免重命名；冲突时重命名本地/项目特定的导入 → [go-packages](../go-packages/SKILL.md)
|
||||
- [ ] **空白导入**：`import _ "pkg"` 仅在 main 包或测试中使用 → [go-packages](../go-packages/SKILL.md)
|
||||
- [ ] **点导入**：仅在测试中用于解决循环依赖 → [go-packages](../go-packages/SKILL.md)
|
||||
|
||||
---
|
||||
|
||||
## 泛型
|
||||
|
||||
- [ ] **何时使用**：仅当多个类型共享相同逻辑且接口不足时 → [go-generics](../go-generics/SKILL.md)
|
||||
- [ ] **类型别名**：使用定义创建新类型；别名仅用于包迁移 → [go-generics](../go-generics/SKILL.md)
|
||||
|
||||
---
|
||||
|
||||
## 测试
|
||||
|
||||
- [ ] **示例**：包含可运行的 `Example` 函数或演示用法的测试 → [go-documentation](../go-documentation/SKILL.md)
|
||||
- [ ] **有用的测试失败信息**：消息包含出了什么错、输入、实际值和期望值；顺序为 `got != want` → [go-testing](../go-testing/SKILL.md)
|
||||
- [ ] **TestMain**：仅当所有测试都需要带清理的公共设置时使用；优先使用作用域化的 helper → [go-testing](../go-testing/SKILL.md)
|
||||
- [ ] **真实传输**：优先使用 `httptest.NewServer` + 真实客户端而非 mock HTTP → [go-testing](../go-testing/SKILL.md)
|
||||
|
||||
---
|
||||
|
||||
## 自动化检查
|
||||
|
||||
运行自动化预审查检查：
|
||||
|
||||
```bash
|
||||
bash scripts/pre-review.sh ./... # 文本输出
|
||||
bash scripts/pre-review.sh --json ./... # 结构化 JSON 输出
|
||||
```
|
||||
|
||||
或手动：`gofmt -l <path> && go vet ./... && golangci-lint run ./...`
|
||||
|
||||
在进入上述清单之前修复所有问题。有关 linter 设置和配置，请参阅 [go-linting](../go-linting/SKILL.md)。
|
||||
|
||||
---
|
||||
|
||||
## 综合示例
|
||||
|
||||
> 在构建生产级 HTTP 服务器并希望验证代码是否正确应用了并发、错误处理、context、文档和命名规范时，阅读 [references/WEB-SERVER.md](references/WEB-SERVER.md)。
|
||||
|
||||
---
|
||||
|
||||
## 相关 Skill
|
||||
|
||||
- **风格基础**：在解决格式化争议或应用"清晰 > 简单 > 简洁"优先级时，请参阅 [go-style-core](../go-style-core/SKILL.md)
|
||||
- **Linting 设置**：在配置 golangci-lint 或将自动化检查添加到 CI 时，请参阅 [go-linting](../go-linting/SKILL.md)
|
||||
- **错误策略**：在审查错误包装、哨兵错误或 handle-once 模式时，请参阅 [go-error-handling](../go-error-handling/SKILL.md)
|
||||
- **命名规范**：在评估标识符名称、接收器名称或包-符号重复时，请参阅 [go-naming](../go-naming/SKILL.md)
|
||||
- **测试模式**：在审查表驱动结构、失败消息或 helper 使用的测试代码时，请参阅 [go-testing](../go-testing/SKILL.md)
|
||||
- **并发安全**：在审查 goroutine 生命周期、channel 使用或互斥锁放置时，请参阅 [go-concurrency](../go-concurrency/SKILL.md)
|
||||
- **日志实践**：在审查日志使用、结构化日志或 slog 配置时，请参阅 [go-logging](../go-logging/SKILL.md)
|
||||
@@ -1,23 +0,0 @@
|
||||
# Code Review: [PR Title]
|
||||
|
||||
## Summary
|
||||
[Brief description of the changes]
|
||||
|
||||
## Findings
|
||||
|
||||
### Must Fix
|
||||
- [ ] [file:line] Description of critical issue
|
||||
|
||||
### Should Fix
|
||||
- [ ] [file:line] Description of recommended improvement
|
||||
|
||||
### Nits
|
||||
- [ ] [file:line] Description of minor suggestion
|
||||
|
||||
## Automated Checks
|
||||
- [ ] `gofmt -d .` — clean
|
||||
- [ ] `go vet ./...` — clean
|
||||
- [ ] `golangci-lint run` — clean
|
||||
|
||||
## Skills Applied
|
||||
[List of go-* skills referenced during review]
|
||||
@@ -1,119 +0,0 @@
|
||||
# Web 服务器：Skill 的综合应用
|
||||
|
||||
本示例展示 Go skill 如何在真实的 HTTP 服务器中协同应用。每个部分
|
||||
引用相关的 skill 以获取详细指导。
|
||||
|
||||
## 结构
|
||||
|
||||
```go
|
||||
package main
|
||||
|
||||
import (
|
||||
"context"
|
||||
"encoding/json"
|
||||
"errors"
|
||||
"fmt"
|
||||
"log/slog"
|
||||
"net/http"
|
||||
"os"
|
||||
"os/signal"
|
||||
"time"
|
||||
)
|
||||
|
||||
// --- 接口（go-interfaces） ---
|
||||
|
||||
// Store 定义了数据访问边界。定义在消费方包中，
|
||||
// 而非实现方包中。
|
||||
type Store interface {
|
||||
GetUser(ctx context.Context, id string) (*User, error)
|
||||
}
|
||||
|
||||
// --- 类型与构造函数（go-naming、go-declarations） ---
|
||||
|
||||
// Server 处理用户 API 的 HTTP 请求。
|
||||
type Server struct {
|
||||
store Store
|
||||
router *http.ServeMux
|
||||
}
|
||||
|
||||
// NewServer 使用给定的依赖创建 Server。
|
||||
// 调用者必须调用 Shutdown 来释放资源。
|
||||
func NewServer(store Store) *Server {
|
||||
s := &Server{store: store}
|
||||
s.router = http.NewServeMux()
|
||||
s.router.HandleFunc("GET /users/{id}", s.handleGetUser)
|
||||
return s
|
||||
}
|
||||
|
||||
// --- 错误处理（go-error-handling） ---
|
||||
|
||||
// 领域错误作为哨兵 —— 使用 errors.Is 进行检查。
|
||||
var ErrNotFound = errors.New("not found")
|
||||
|
||||
// --- HTTP 处理器（go-control-flow、go-context、go-error-handling） ---
|
||||
|
||||
func (s *Server) handleGetUser(w http.ResponseWriter, r *http.Request) {
|
||||
ctx := r.Context() // go-context：从 request 派生
|
||||
id := r.PathValue("id")
|
||||
|
||||
user, err := s.store.GetUser(ctx, id)
|
||||
if err != nil {
|
||||
if errors.Is(err, ErrNotFound) { // go-error-handling：errors.Is
|
||||
http.Error(w, "user not found", http.StatusNotFound)
|
||||
return // go-control-flow：提前返回
|
||||
}
|
||||
// HTTP 处理器是"记录或返回"规则的例外：在服务端记录详细信息，向客户端返回脱敏错误。
|
||||
slog.Error("GetUser failed", "id", id, "err", err)
|
||||
http.Error(w, "internal error", http.StatusInternalServerError)
|
||||
return
|
||||
}
|
||||
|
||||
w.Header().Set("Content-Type", "application/json")
|
||||
json.NewEncoder(w).Encode(user)
|
||||
}
|
||||
|
||||
// --- 优雅关闭（go-concurrency、go-defensive） ---
|
||||
|
||||
func main() {
|
||||
store := NewDBStore(os.Getenv("DATABASE_URL"))
|
||||
srv := NewServer(store)
|
||||
|
||||
httpSrv := &http.Server{
|
||||
Addr: ":8080",
|
||||
Handler: srv.router,
|
||||
ReadTimeout: 5 * time.Second, // go-defensive：使用 time.Duration
|
||||
WriteTimeout: 10 * time.Second,
|
||||
}
|
||||
|
||||
// go-concurrency：goroutine 生命周期清晰
|
||||
go func() {
|
||||
sigCh := make(chan os.Signal, 1) // go-concurrency：channel 大小为 1
|
||||
signal.Notify(sigCh, os.Interrupt)
|
||||
<-sigCh
|
||||
|
||||
ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
|
||||
defer cancel() // go-defensive：defer 清理
|
||||
httpSrv.Shutdown(ctx)
|
||||
}()
|
||||
|
||||
slog.Info("starting server", "addr", httpSrv.Addr)
|
||||
if err := httpSrv.ListenAndServe(); !errors.Is(err, http.ErrServerClosed) {
|
||||
slog.Error("server error", "err", err)
|
||||
os.Exit(1) // go-packages：仅在 main 中退出
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 应用的 Skill
|
||||
|
||||
| 领域 | Skill | 演示内容 |
|
||||
|------|-------|----------|
|
||||
| 接口在消费方 | [go-interfaces](../../go-interfaces/SKILL.md) | `Store` 在使用处定义 |
|
||||
| 命名 | [go-naming](../../go-naming/SKILL.md) | MixedCaps、接收器缩写、清晰的函数名 |
|
||||
| 错误处理 | [go-error-handling](../../go-error-handling/SKILL.md) | 哨兵错误、`errors.Is`、记录或返回 |
|
||||
| Context | [go-context](../../go-context/SKILL.md) | 从 request 派生，逐层传递 |
|
||||
| 控制流 | [go-control-flow](../../go-control-flow/SKILL.md) | 错误情况的提前返回 |
|
||||
| 并发 | [go-concurrency](../../go-concurrency/SKILL.md) | 清晰的 goroutine 生命周期、channel 大小 |
|
||||
| 防御性 | [go-defensive](../../go-defensive/SKILL.md) | `defer cancel()`、`time.Duration`、优雅关闭 |
|
||||
| 包管理 | [go-packages](../../go-packages/SKILL.md) | 仅在 `main()` 中退出 |
|
||||
| 日志 | [go-error-handling](../../go-error-handling/SKILL.md) | 结构化 slog，错误只处理一次 |
|
||||
@@ -1,246 +0,0 @@
|
||||
#!/usr/bin/env bash
|
||||
set -euo pipefail
|
||||
|
||||
VERSION="1.0.0"
|
||||
SCRIPT_NAME="$(basename "$0")"
|
||||
|
||||
usage() {
|
||||
cat <<EOF
|
||||
$SCRIPT_NAME v$VERSION — Run automated pre-review checks on Go code
|
||||
|
||||
USAGE
|
||||
bash $SCRIPT_NAME [options] [path]
|
||||
|
||||
DESCRIPTION
|
||||
Runs gofmt, go vet, and golangci-lint against the target path and
|
||||
reports any findings. Use before manual code review to catch
|
||||
mechanical issues early.
|
||||
|
||||
Exits 0 if all checks pass, 1 if issues found, 2 on error.
|
||||
|
||||
OPTIONS
|
||||
-h, --help Show this help message
|
||||
-v, --version Show version
|
||||
--json Output results as JSON
|
||||
--force Run even if golangci-lint is not installed (skip it)
|
||||
--limit N Max items reported per section (0 = unlimited, default: 0)
|
||||
|
||||
ARGUMENTS
|
||||
path Package pattern to check (default: ./...)
|
||||
|
||||
EXAMPLES
|
||||
bash $SCRIPT_NAME
|
||||
bash $SCRIPT_NAME ./pkg/...
|
||||
bash $SCRIPT_NAME --json ./cmd/server/...
|
||||
bash $SCRIPT_NAME --force ./...
|
||||
bash $SCRIPT_NAME --json --limit 10 ./...
|
||||
EOF
|
||||
}
|
||||
|
||||
json_escape() {
|
||||
local s="$1"
|
||||
s="${s//\\/\\\\}"
|
||||
s="${s//\"/\\\"}"
|
||||
s="${s//$'\t'/\\t}"
|
||||
s="${s//$'\r'/}"
|
||||
s="${s//$'\n'/\\n}"
|
||||
printf '%s' "$s"
|
||||
}
|
||||
|
||||
JSON_OUTPUT=false
|
||||
FORCE=false
|
||||
LIMIT=0
|
||||
TARGET=""
|
||||
|
||||
while [[ $# -gt 0 ]]; do
|
||||
case "$1" in
|
||||
-h|--help) usage; exit 0 ;;
|
||||
-v|--version) echo "$SCRIPT_NAME v$VERSION"; exit 0 ;;
|
||||
--json) JSON_OUTPUT=true; shift ;;
|
||||
--force) FORCE=true; shift ;;
|
||||
--limit) LIMIT="${2:?error: --limit requires a number}"; shift 2 ;;
|
||||
-*) echo "error: unknown option: $1" >&2; usage >&2; exit 2 ;;
|
||||
*) TARGET="$1"; shift ;;
|
||||
esac
|
||||
done
|
||||
|
||||
TARGET="${TARGET:-./...}"
|
||||
|
||||
if ! command -v go &>/dev/null; then
|
||||
echo "error: go is not installed or not in PATH" >&2
|
||||
exit 2
|
||||
fi
|
||||
|
||||
if ! command -v gofmt &>/dev/null; then
|
||||
echo "error: gofmt is not installed or not in PATH" >&2
|
||||
exit 2
|
||||
fi
|
||||
|
||||
GOFMT_STATUS="pass"
|
||||
GOFMT_FINDINGS=()
|
||||
GOFMT_DIR="${TARGET%%/...}"
|
||||
GOFMT_DIR="${GOFMT_DIR:-.}"
|
||||
UNFORMATTED=$(gofmt -l "$GOFMT_DIR" 2>&1) || true
|
||||
if [[ -n "$UNFORMATTED" ]]; then
|
||||
GOFMT_STATUS="fail"
|
||||
while IFS= read -r f; do
|
||||
[[ -n "$f" ]] && GOFMT_FINDINGS+=("$f")
|
||||
done <<< "$UNFORMATTED"
|
||||
fi
|
||||
|
||||
GOVET_STATUS="pass"
|
||||
GOVET_OUTPUT=""
|
||||
if ! GOVET_OUTPUT=$(go vet "$TARGET" 2>&1); then
|
||||
GOVET_STATUS="fail"
|
||||
fi
|
||||
|
||||
LINT_STATUS="skip"
|
||||
LINT_OUTPUT=""
|
||||
if command -v golangci-lint &>/dev/null; then
|
||||
LINT_STATUS="pass"
|
||||
if ! LINT_OUTPUT=$(golangci-lint run "$TARGET" 2>&1); then
|
||||
LINT_STATUS="fail"
|
||||
fi
|
||||
elif ! $FORCE; then
|
||||
echo "error: golangci-lint not installed (use --force to skip)" >&2
|
||||
exit 2
|
||||
fi
|
||||
|
||||
FAILED=0
|
||||
[[ "$GOFMT_STATUS" == "fail" ]] && FAILED=1
|
||||
[[ "$GOVET_STATUS" == "fail" ]] && FAILED=1
|
||||
[[ "$LINT_STATUS" == "fail" ]] && FAILED=1
|
||||
|
||||
if $JSON_OUTPUT; then
|
||||
GOFMT_TRUNCATED=false
|
||||
GOFMT_DISPLAY=("${GOFMT_FINDINGS[@]+"${GOFMT_FINDINGS[@]}"}")
|
||||
if [[ $LIMIT -gt 0 && ${#GOFMT_DISPLAY[@]} -gt $LIMIT ]]; then
|
||||
GOFMT_DISPLAY=("${GOFMT_FINDINGS[@]:0:$LIMIT}")
|
||||
GOFMT_TRUNCATED=true
|
||||
fi
|
||||
|
||||
GOFMT_JSON="["
|
||||
first=true
|
||||
for f in "${GOFMT_DISPLAY[@]+"${GOFMT_DISPLAY[@]}"}"; do
|
||||
$first || GOFMT_JSON+=","
|
||||
first=false
|
||||
GOFMT_JSON+="\"$(json_escape "$f")\""
|
||||
done
|
||||
GOFMT_JSON+="]"
|
||||
|
||||
GOVET_TRUNCATED=false
|
||||
GOVET_DISPLAY="$GOVET_OUTPUT"
|
||||
if [[ $LIMIT -gt 0 && -n "$GOVET_OUTPUT" ]]; then
|
||||
GOVET_ARR=()
|
||||
while IFS= read -r line; do
|
||||
GOVET_ARR+=("$line")
|
||||
done <<< "$GOVET_OUTPUT"
|
||||
if [[ ${#GOVET_ARR[@]} -gt $LIMIT ]]; then
|
||||
GOVET_DISPLAY=""
|
||||
for (( i=0; i<LIMIT; i++ )); do
|
||||
[[ -n "$GOVET_DISPLAY" ]] && GOVET_DISPLAY+=$'\n'
|
||||
GOVET_DISPLAY+="${GOVET_ARR[$i]}"
|
||||
done
|
||||
GOVET_TRUNCATED=true
|
||||
fi
|
||||
fi
|
||||
GOVET_ESC="$(json_escape "$GOVET_DISPLAY")"
|
||||
|
||||
LINT_TRUNCATED=false
|
||||
LINT_DISPLAY="$LINT_OUTPUT"
|
||||
if [[ $LIMIT -gt 0 && -n "$LINT_OUTPUT" ]]; then
|
||||
LINT_ARR=()
|
||||
while IFS= read -r line; do
|
||||
LINT_ARR+=("$line")
|
||||
done <<< "$LINT_OUTPUT"
|
||||
if [[ ${#LINT_ARR[@]} -gt $LIMIT ]]; then
|
||||
LINT_DISPLAY=""
|
||||
for (( i=0; i<LIMIT; i++ )); do
|
||||
[[ -n "$LINT_DISPLAY" ]] && LINT_DISPLAY+=$'\n'
|
||||
LINT_DISPLAY+="${LINT_ARR[$i]}"
|
||||
done
|
||||
LINT_TRUNCATED=true
|
||||
fi
|
||||
fi
|
||||
LINT_ESC="$(json_escape "$LINT_DISPLAY")"
|
||||
|
||||
GOFMT_TRUNC=""
|
||||
$GOFMT_TRUNCATED && GOFMT_TRUNC=',"truncated":true'
|
||||
GOVET_TRUNC=""
|
||||
$GOVET_TRUNCATED && GOVET_TRUNC=',"truncated":true'
|
||||
LINT_TRUNC=""
|
||||
$LINT_TRUNCATED && LINT_TRUNC=',"truncated":true'
|
||||
|
||||
cat <<EOF
|
||||
{"gofmt":{"status":"$GOFMT_STATUS","files":$GOFMT_JSON$GOFMT_TRUNC},"govet":{"status":"$GOVET_STATUS","output":"$GOVET_ESC"$GOVET_TRUNC},"golangci_lint":{"status":"$LINT_STATUS","output":"$LINT_ESC"$LINT_TRUNC},"passed":$( [[ $FAILED -eq 0 ]] && echo true || echo false )}
|
||||
EOF
|
||||
else
|
||||
echo "=== gofmt ==="
|
||||
if [[ "$GOFMT_STATUS" == "fail" ]]; then
|
||||
echo "Unformatted files:"
|
||||
GOFMT_COUNT=0
|
||||
for f in "${GOFMT_FINDINGS[@]}"; do
|
||||
GOFMT_COUNT=$((GOFMT_COUNT + 1))
|
||||
if [[ $LIMIT -gt 0 && $GOFMT_COUNT -gt $LIMIT ]]; then
|
||||
echo " ... ($(( ${#GOFMT_FINDINGS[@]} - LIMIT )) more items truncated)"
|
||||
break
|
||||
fi
|
||||
echo " $f"
|
||||
done
|
||||
else
|
||||
echo "OK"
|
||||
fi
|
||||
|
||||
echo ""
|
||||
echo "=== go vet ==="
|
||||
if [[ "$GOVET_STATUS" == "fail" ]]; then
|
||||
if [[ $LIMIT -gt 0 ]]; then
|
||||
GOVET_ARR=()
|
||||
while IFS= read -r line; do
|
||||
GOVET_ARR+=("$line")
|
||||
done <<< "$GOVET_OUTPUT"
|
||||
for (( i=0; i<${#GOVET_ARR[@]} && i<LIMIT; i++ )); do
|
||||
echo "${GOVET_ARR[$i]}"
|
||||
done
|
||||
if [[ ${#GOVET_ARR[@]} -gt $LIMIT ]]; then
|
||||
echo "... ($(( ${#GOVET_ARR[@]} - LIMIT )) more items truncated)"
|
||||
fi
|
||||
else
|
||||
echo "$GOVET_OUTPUT"
|
||||
fi
|
||||
else
|
||||
echo "OK"
|
||||
fi
|
||||
|
||||
echo ""
|
||||
echo "=== golangci-lint ==="
|
||||
if [[ "$LINT_STATUS" == "skip" ]]; then
|
||||
echo "Skipped (not installed)"
|
||||
elif [[ "$LINT_STATUS" == "fail" ]]; then
|
||||
if [[ $LIMIT -gt 0 ]]; then
|
||||
LINT_ARR=()
|
||||
while IFS= read -r line; do
|
||||
LINT_ARR+=("$line")
|
||||
done <<< "$LINT_OUTPUT"
|
||||
for (( i=0; i<${#LINT_ARR[@]} && i<LIMIT; i++ )); do
|
||||
echo "${LINT_ARR[$i]}"
|
||||
done
|
||||
if [[ ${#LINT_ARR[@]} -gt $LIMIT ]]; then
|
||||
echo "... ($(( ${#LINT_ARR[@]} - LIMIT )) more items truncated)"
|
||||
fi
|
||||
else
|
||||
echo "$LINT_OUTPUT"
|
||||
fi
|
||||
else
|
||||
echo "OK"
|
||||
fi
|
||||
|
||||
echo ""
|
||||
if [[ $FAILED -eq 1 ]]; then
|
||||
echo "Pre-review checks FAILED — fix issues before manual review."
|
||||
else
|
||||
echo "All pre-review checks passed."
|
||||
fi
|
||||
fi
|
||||
|
||||
exit $FAILED
|
||||
@@ -1,191 +0,0 @@
|
||||
---
|
||||
name: go-concurrency
|
||||
description: Use when writing concurrent Go code — goroutines, channels, mutexes, or thread-safety guarantees. Also use when parallelizing work, fixing data races, or protecting shared state, even if the user doesn't explicitly mention concurrency primitives. Does not cover context.Context patterns (see go-context).
|
||||
license: Apache-2.0
|
||||
compatibility: Requires go.uber.org/atomic for atomic operation wrappers
|
||||
metadata:
|
||||
sources: "Effective Go, Google Style Guide, Uber Style Guide"
|
||||
---
|
||||
|
||||
# Go 并发
|
||||
|
||||
## Goroutine 生命周期
|
||||
|
||||
> **规范**：当你启动 goroutine 时，要明确它们何时或是否退出。
|
||||
|
||||
Goroutine 可能因阻塞在 channel 的发送/接收上而泄漏。GC **不会终止**被阻塞的 goroutine，即使没有其他 goroutine 持有对该 channel 的引用。即使不泄漏的在途 goroutine 也会导致 panic（在已关闭的 channel 上发送）、数据竞争、内存问题和资源泄漏。
|
||||
|
||||
### 核心规则
|
||||
|
||||
1. **每个 goroutine 都需要停止机制** —— 可预测的结束时间、取消信号，或两者兼有
|
||||
2. **代码必须能够等待** goroutine 完成
|
||||
3. **不在 `init()` 中启动 goroutine** —— 改为暴露生命周期方法（`Close`、`Stop`、`Shutdown`）
|
||||
4. **保持同步作用域化** —— 限制在函数作用域内，将逻辑分解为同步函数
|
||||
|
||||
```go
|
||||
// 好：使用 WaitGroup 明确生命周期
|
||||
var wg sync.WaitGroup
|
||||
for item := range queue {
|
||||
wg.Add(1)
|
||||
go func() { defer wg.Done(); process(ctx, item) }()
|
||||
}
|
||||
wg.Wait()
|
||||
```
|
||||
|
||||
```go
|
||||
// 不好：无法停止或等待
|
||||
go func() { for { flush(); time.Sleep(delay) } }()
|
||||
```
|
||||
|
||||
使用 [go.uber.org/goleak](https://pkg.go.dev/go.uber.org/goleak) **检测泄漏**。
|
||||
|
||||
> **原则**：永远不要在不知道 goroutine 将如何停止的情况下启动它。
|
||||
|
||||
> 在实现 stop/done channel 模式、goroutine 等待策略或
|
||||
> 生命周期管理的 worker 时，阅读 [references/GOROUTINE-PATTERNS.md](references/GOROUTINE-PATTERNS.md)。
|
||||
|
||||
---
|
||||
|
||||
## 通过通信共享
|
||||
|
||||
> "不要通过共享内存来通信；而是通过通信来共享内存。"
|
||||
|
||||
这是 Go 并发设计的基础原则。使用 **channel** 进行所有权转移和协调 —— 当一个 goroutine 生产值，另一个消费它时使用。当多个 goroutine 访问共享状态且 channel 会增加不必要的复杂性时，使用 **互斥锁**。
|
||||
|
||||
**默认使用 channel。** 当问题本质上是保护共享数据结构（例如缓存或计数器）而非在 goroutine 之间传递数据时，退回到 `sync.Mutex` / `sync.RWMutex`。
|
||||
|
||||
---
|
||||
|
||||
## 同步函数
|
||||
|
||||
> **规范**：优先使用同步函数而非异步函数。
|
||||
|
||||
| 优势 | 原因 |
|
||||
|---|---|
|
||||
| 局部化 goroutine | 生命周期更容易推理 |
|
||||
| 避免泄漏和竞争 | 更容易防止资源泄漏和数据竞争 |
|
||||
| 更容易测试 | 直接检查输入/输出，无需轮询 |
|
||||
| 调用方灵活性 | 调用方在需要时添加并发 |
|
||||
|
||||
> **建议**：在调用方移除不必要的并发是相当困难的（有时是不可能的）。让调用方在需要时添加并发。
|
||||
|
||||
> 在编写同步优先的 API（调用方可以将其包装在 goroutine 中）时，
|
||||
> 阅读 [references/GOROUTINE-PATTERNS.md](references/GOROUTINE-PATTERNS.md)。
|
||||
|
||||
---
|
||||
|
||||
## 零值互斥锁
|
||||
|
||||
`sync.Mutex` 和 `sync.RWMutex` 的零值是有效的 —— 几乎不需要互斥锁的指针。
|
||||
|
||||
```go
|
||||
// 好：零值有效 // 不好：不必要的指针
|
||||
var mu sync.Mutex mu := new(sync.Mutex)
|
||||
```
|
||||
|
||||
**不要嵌入互斥锁** —— 使用命名的 `mu` 字段，使 `Lock`/`Unlock` 保持为实现细节，而非导出的 API。
|
||||
|
||||
> 在实现互斥锁保护的 struct 或决定如何组织互斥锁字段时，
|
||||
> 阅读 [references/SYNC-PRIMITIVES.md](references/SYNC-PRIMITIVES.md)。
|
||||
|
||||
---
|
||||
|
||||
## Channel 方向
|
||||
|
||||
> **规范**：尽可能指定 channel 方向。
|
||||
|
||||
方向可以防止错误（编译器会捕获对仅接收 channel 的关闭操作），传达所有权，并且具有自文档化效果。
|
||||
|
||||
```go
|
||||
func produce(out chan<- int) { /* 仅发送 */ }
|
||||
func consume(in <-chan int) { /* 仅接收 */ }
|
||||
func transform(in <-chan int, out chan<- int) { /* 双向 */ }
|
||||
```
|
||||
|
||||
### Channel 大小：一或零
|
||||
|
||||
Channel 的大小应为 **零**（无缓冲）或 **一**。其他任何大小都需要给出理由：
|
||||
|
||||
- 大小是如何确定的
|
||||
- 什么机制防止 channel 在负载下填满
|
||||
- 当写入者阻塞时会发生什么
|
||||
|
||||
```go
|
||||
c := make(chan int) // 无缓冲 —— 好
|
||||
c := make(chan int, 1) // 大小为 1 —— 好
|
||||
c := make(chan int, 64) // 任意大小 —— 需要给出理由
|
||||
```
|
||||
|
||||
> 在审查详细的 channel 方向示例及易出错模式时，
|
||||
> 阅读 [references/SYNC-PRIMITIVES.md](references/SYNC-PRIMITIVES.md)。
|
||||
|
||||
---
|
||||
|
||||
## 原子操作
|
||||
|
||||
使用 `atomic.Bool`、`atomic.Int64` 等（Go 1.19 起标准库 `sync/atomic` 提供，或 [go.uber.org/atomic](https://pkg.go.dev/go.uber.org/atomic)）进行类型安全的原子操作。原始的 `int32`/`int64` 字段容易在某些代码路径上忘记原子访问。
|
||||
|
||||
```go
|
||||
// 好：类型安全 // 不好：容易忘记
|
||||
var running atomic.Bool var running int32 // 原子操作
|
||||
running.Store(true) atomic.StoreInt32(&running, 1)
|
||||
running.Load() running == 1 // 竞争！
|
||||
```
|
||||
|
||||
> 在 sync/atomic 和 go.uber.org/atomic 之间选择，或在 struct 中实现原子
|
||||
> 状态标志时，阅读 [references/SYNC-PRIMITIVES.md](references/SYNC-PRIMITIVES.md)。
|
||||
|
||||
---
|
||||
|
||||
## 并发文档
|
||||
|
||||
> **建议**：当线程安全性从操作类型不明显时，添加文档说明。
|
||||
|
||||
Go 用户假设只读操作可以安全地并发使用，而修改操作则不行。在以下情况添加并发文档：
|
||||
|
||||
1. **读取与修改不明确** —— 例如，会修改 LRU 状态的 `Lookup`
|
||||
2. **API 提供同步** —— 例如，线程安全的客户端
|
||||
3. **接口有并发要求** —— 在类型定义中添加文档
|
||||
|
||||
---
|
||||
|
||||
## Context 使用
|
||||
|
||||
> 有关 context.Context 的指导（参数位置、struct 存储、自定义
|
||||
> 类型、派生模式），请参阅专门的
|
||||
> [go-context](../go-context/SKILL.md) skill。
|
||||
|
||||
---
|
||||
|
||||
## 使用 Channel 的缓冲池
|
||||
|
||||
使用有缓冲 channel 作为空闲列表来复用已分配的缓冲区。这种"泄漏缓冲"模式使用带 `default` 的 `select` 进行非阻塞操作。
|
||||
|
||||
> 在实现带可复用缓冲区的 worker pool 或在基于 channel 的池和
|
||||
> `sync.Pool` 之间选择时，阅读 [references/BUFFER-POOLING.md](references/BUFFER-POOLING.md)。
|
||||
|
||||
---
|
||||
|
||||
## 高级模式
|
||||
|
||||
> 在实现使用 channel 的 channel 进行请求-响应多路复用，或
|
||||
> 跨核心的 CPU 密集型并行计算时，阅读 [references/ADVANCED-PATTERNS.md](references/ADVANCED-PATTERNS.md)。
|
||||
|
||||
---
|
||||
|
||||
## 相关 Skill
|
||||
|
||||
- **Context 传播**：在通过 goroutine 传递取消、截止时间或请求作用域值时，请参阅 [go-context](../go-context/SKILL.md)
|
||||
- **错误处理**：在从 goroutine 传播错误或使用 errgroup 时，请参阅 [go-error-handling](../go-error-handling/SKILL.md)
|
||||
- **防御性加固**：在 API 边界保护共享状态或使用 defer 清理时，请参阅 [go-defensive](../go-defensive/SKILL.md)
|
||||
- **接口设计**：在为包含 sync 原语的类型选择接收器类型时，请参阅 [go-interfaces](../go-interfaces/SKILL.md)
|
||||
|
||||
### 外部资源
|
||||
|
||||
- [永远不要在不知道 goroutine 将如何停止的情况下启动它](https://dave.cheney.net/2016/12/22/never-start-a-goroutine-without-knowing-how-it-will-stop)
|
||||
—— Dave Cheney
|
||||
- [重新思考经典并发模式](https://www.youtube.com/watch?v=5zXAHh5tJqQ) —— Bryan Mills
|
||||
（GopherCon 2018）
|
||||
- [Go 程序何时结束](https://changelog.com/gotime/165) —— Go Time 播客
|
||||
- [go.uber.org/goleak](https://pkg.go.dev/go.uber.org/goleak) —— 用于测试的 Goroutine 泄漏检测器
|
||||
- [go.uber.org/atomic](https://pkg.go.dev/go.uber.org/atomic) —— 类型安全的原子操作
|
||||
@@ -1,132 +0,0 @@
|
||||
# 高级并发模式
|
||||
|
||||
来自 Effective Go 的高级并发模式详细参考。这些模式适用于特定场景 —— 在需要请求/响应多路复用或 CPU 密集型并行化时使用。
|
||||
|
||||
---
|
||||
|
||||
## Channel 的 Channel
|
||||
|
||||
> **来源**：Effective Go
|
||||
|
||||
Channel 是一等公民值，可以像其他值一样被分配和传递。一个强大的模式是在请求结构体中嵌入 **回复 channel**，让每个客户端提供自己的应答路径：
|
||||
|
||||
```go
|
||||
type Request struct {
|
||||
args []int
|
||||
f func([]int) int
|
||||
resultChan chan int
|
||||
}
|
||||
```
|
||||
|
||||
客户端发送一个包含函数、参数和接收结果 channel 的请求：
|
||||
|
||||
```go
|
||||
request := &Request{[]int{3, 4, 5}, sum, make(chan int)}
|
||||
clientRequests <- request
|
||||
fmt.Printf("answer: %d\n", <-request.resultChan)
|
||||
```
|
||||
|
||||
服务端处理器从队列中读取请求，并将结果发送回每个请求的回复 channel：
|
||||
|
||||
```go
|
||||
func handle(queue chan *Request) {
|
||||
for req := range queue {
|
||||
req.resultChan <- req.f(req.args)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
这个模式构成了限速、并行、非阻塞 RPC 系统的基础，无需任何互斥锁。
|
||||
|
||||
---
|
||||
|
||||
## CPU 密集型并行化
|
||||
|
||||
> **来源**：Effective Go（现代化版本）
|
||||
|
||||
当计算可以分解为独立的部分时，使用 `sync.WaitGroup` 等待完成，将其并行化到多个 CPU 核心上：
|
||||
|
||||
```go
|
||||
type Vector []float64
|
||||
|
||||
func (v Vector) DoSome(i, n int, u Vector) {
|
||||
for ; i < n; i++ {
|
||||
v[i] += u.Op(v[i])
|
||||
}
|
||||
}
|
||||
|
||||
func (v Vector) DoAll(u Vector) {
|
||||
numCPU := runtime.NumCPU()
|
||||
var wg sync.WaitGroup
|
||||
wg.Add(numCPU)
|
||||
for i := 0; i < numCPU; i++ {
|
||||
go func(i int) {
|
||||
defer wg.Done()
|
||||
v.DoSome(i*len(v)/numCPU, (i+1)*len(v)/numCPU, u)
|
||||
}(i)
|
||||
}
|
||||
wg.Wait()
|
||||
}
|
||||
```
|
||||
|
||||
使用 `runtime.NumCPU()` 获取硬件核心数，或使用 `runtime.GOMAXPROCS(0)` 以遵循用户的资源配置。
|
||||
|
||||
> **重要**：不要混淆并发（将程序组织为独立执行的组件）和并行（在多个 CPU 上同时执行计算）。Go 是一门并发语言；并非所有并行化问题都适合它的模型。
|
||||
|
||||
---
|
||||
|
||||
## 常见错误
|
||||
|
||||
### 忘记通知完成
|
||||
|
||||
如果 goroutine 从未调用 `wg.Done()`（或从未在 done channel 上发送），等待的 goroutine 将永远阻塞：
|
||||
|
||||
```go
|
||||
// 不好：缺少 wg.Done —— 死锁
|
||||
var wg sync.WaitGroup
|
||||
wg.Add(1)
|
||||
go func() {
|
||||
doWork()
|
||||
}()
|
||||
wg.Wait()
|
||||
|
||||
// 好：始终 defer wg.Done
|
||||
var wg sync.WaitGroup
|
||||
wg.Add(1)
|
||||
go func() {
|
||||
defer wg.Done()
|
||||
doWork()
|
||||
}()
|
||||
wg.Wait()
|
||||
```
|
||||
|
||||
### 无限制的 goroutine 创建
|
||||
|
||||
为每个工作项无限制地启动 goroutine 可能会耗尽内存或压垮下游资源。使用信号量来限制并发数：
|
||||
|
||||
```go
|
||||
// 不好：一次性创建 len(items) 个 goroutine
|
||||
var wg sync.WaitGroup
|
||||
for _, item := range items {
|
||||
wg.Add(1)
|
||||
go func(it Item) {
|
||||
defer wg.Done()
|
||||
process(it)
|
||||
}(item)
|
||||
}
|
||||
wg.Wait()
|
||||
|
||||
// 好：信号量将并发限制为 maxWorkers
|
||||
var wg sync.WaitGroup
|
||||
sem := make(chan struct{}, maxWorkers)
|
||||
for _, item := range items {
|
||||
wg.Add(1)
|
||||
sem <- struct{}{}
|
||||
go func(it Item) {
|
||||
defer wg.Done()
|
||||
defer func() { <-sem }()
|
||||
process(it)
|
||||
}(item)
|
||||
}
|
||||
wg.Wait()
|
||||
```
|
||||
@@ -1,73 +0,0 @@
|
||||
# 使用 Channel 的缓冲池
|
||||
|
||||
使用有缓冲 channel 作为空闲列表来复用已分配的缓冲区，避免重复分配。这种"泄漏缓冲"模式使用带 `default` 的 `select` 进行非阻塞操作。
|
||||
|
||||
> **来源**：Effective Go
|
||||
|
||||
```go
|
||||
var freeList = make(chan *Buffer, 100) // 有缓冲 channel 作为空闲列表
|
||||
|
||||
// 客户端：从空闲列表获取缓冲区或分配新的
|
||||
func getBuffer() *Buffer {
|
||||
select {
|
||||
case b := <-freeList:
|
||||
return b // 复用已有缓冲区
|
||||
default:
|
||||
return new(Buffer) // 空闲列表为空；分配新缓冲区
|
||||
}
|
||||
}
|
||||
|
||||
// 服务端：如有空间则将缓冲区归还空闲列表，否则丢弃
|
||||
func putBuffer(b *Buffer) {
|
||||
b.Reset() // 为重用做准备
|
||||
select {
|
||||
case freeList <- b:
|
||||
// 缓冲区已归还空闲列表
|
||||
default:
|
||||
// 空闲列表已满；丢弃缓冲区（GC 会回收）
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 工作原理
|
||||
|
||||
1. **非阻塞接收**：客户端尝试从 `freeList` 获取缓冲区。如果为空，`default` 分支运行并分配新缓冲区。
|
||||
2. **非阻塞发送**：服务端尝试归还缓冲区。如果 `freeList` 已满，`default` 分支运行，缓冲区被丢弃等待垃圾回收。
|
||||
3. **有限内存**：channel 容量（100）限制了池中缓冲区的数量，防止无限增长。
|
||||
|
||||
当分配成本较高且缓冲区复用有益，但你不希望在池空或池满时出现阻塞行为时，这种模式非常有用。
|
||||
|
||||
## 何时使用
|
||||
|
||||
- 高频分配相似大小的对象
|
||||
- 分配开销影响性能的代码路径
|
||||
- 需要限制内存使用量的场景
|
||||
|
||||
## 生产环境替代方案
|
||||
|
||||
对于生产代码，考虑使用 `sync.Pool`，它提供类似功能并与垃圾收集器有更好的集成：
|
||||
|
||||
```go
|
||||
var bufferPool = sync.Pool{
|
||||
New: func() any {
|
||||
return new(Buffer)
|
||||
},
|
||||
}
|
||||
|
||||
func getBuffer() *Buffer {
|
||||
return bufferPool.Get().(*Buffer)
|
||||
}
|
||||
|
||||
func putBuffer(b *Buffer) {
|
||||
b.Reset()
|
||||
bufferPool.Put(b)
|
||||
}
|
||||
```
|
||||
|
||||
`sync.Pool` 的优势：
|
||||
- 垃圾收集期间自动清理
|
||||
- 无需管理池大小
|
||||
- 天生线程安全
|
||||
- 高并发下性能更好
|
||||
|
||||
基于 channel 的方式对于理解 Go 的并发原语以及需要更多控制池行为的场景仍然很有价值。
|
||||
@@ -1,126 +0,0 @@
|
||||
# Goroutine 生命周期模式
|
||||
|
||||
管理 goroutine 生命周期的详细模式 —— 确保每个 goroutine 都有清晰的启动/停止机制并防止资源泄漏。
|
||||
|
||||
---
|
||||
|
||||
## 使生命周期清晰
|
||||
|
||||
> WaitGroup 示例和作用域规则在父 skill（SKILL.md § Goroutine 生命周期，核心规则）中。本参考涵盖：stop/done channel 模式、等待策略、init() 生命周期示例和同步 API 设计。
|
||||
|
||||
---
|
||||
|
||||
## Stop/Done Channel 模式
|
||||
|
||||
每个 goroutine 必须有可预测的停止机制。使用 stop channel 通知关闭，使用 done channel 确认退出：
|
||||
|
||||
```go
|
||||
var (
|
||||
stop = make(chan struct{}) // 通知 goroutine 停止
|
||||
done = make(chan struct{}) // 通知我们 goroutine 已退出
|
||||
)
|
||||
go func() {
|
||||
defer close(done)
|
||||
ticker := time.NewTicker(delay)
|
||||
defer ticker.Stop()
|
||||
for {
|
||||
select {
|
||||
case <-ticker.C:
|
||||
flush()
|
||||
case <-stop:
|
||||
return
|
||||
}
|
||||
}
|
||||
}()
|
||||
|
||||
// 关闭时：
|
||||
close(stop) // 通知 goroutine 停止
|
||||
<-done // 并等待它退出
|
||||
```
|
||||
|
||||
在已关闭的 channel 上发送会 panic —— 始终使用 `close()` 来发信号，不要直接发送：
|
||||
|
||||
```go
|
||||
ch := make(chan int)
|
||||
close(ch)
|
||||
ch <- 13 // panic: 在已关闭的 channel 上发送
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 等待 Goroutine
|
||||
|
||||
> 多 goroutine 的 `sync.WaitGroup` 模式在父 skill 中（SKILL.md § Goroutine 生命周期）。以下是单 goroutine 的 done-channel 替代方案。
|
||||
|
||||
为单个 goroutine 使用 done channel：
|
||||
|
||||
```go
|
||||
done := make(chan struct{})
|
||||
go func() {
|
||||
defer close(done)
|
||||
// 工作...
|
||||
}()
|
||||
<-done // 等待 goroutine 完成
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 不在 init() 中使用 Goroutine
|
||||
|
||||
> 核心规则在父 skill 中（SKILL.md § 核心规则，规则 3）。以下是展示生命周期管理的扩展示例。
|
||||
|
||||
```go
|
||||
// 不好：创建了不可控的后台 goroutine
|
||||
func init() {
|
||||
go doWork()
|
||||
}
|
||||
```
|
||||
|
||||
```go
|
||||
// 好：显式的生命周期管理
|
||||
type Worker struct {
|
||||
stop chan struct{}
|
||||
done chan struct{}
|
||||
}
|
||||
|
||||
func NewWorker() *Worker {
|
||||
w := &Worker{
|
||||
stop: make(chan struct{}),
|
||||
done: make(chan struct{}),
|
||||
}
|
||||
go w.doWork()
|
||||
return w
|
||||
}
|
||||
|
||||
func (w *Worker) Shutdown() {
|
||||
close(w.stop)
|
||||
<-w.done
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 优先使用同步函数
|
||||
|
||||
> 理由和优势表在父 skill 中（SKILL.md § 同步函数）。以下是具体的代码示例。
|
||||
|
||||
```go
|
||||
// 好：同步函数 - 调用方控制并发
|
||||
func ProcessItems(items []Item) ([]Result, error) {
|
||||
var results []Result
|
||||
for _, item := range items {
|
||||
result, err := processItem(item)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
results = append(results, result)
|
||||
}
|
||||
return results, nil
|
||||
}
|
||||
|
||||
// 调用方可以在需要时添加并发：
|
||||
go func() {
|
||||
results, err := ProcessItems(items)
|
||||
// 处理结果
|
||||
}()
|
||||
```
|
||||
@@ -1,110 +0,0 @@
|
||||
# 同步原语模式
|
||||
|
||||
互斥锁和原子操作的详细模式 —— 涵盖互斥锁嵌入陷阱和类型安全的原子访问。
|
||||
|
||||
---
|
||||
|
||||
## 不要嵌入互斥锁
|
||||
|
||||
如果你通过指针使用结构体，互斥锁应该是非指针字段。不要在结构体中嵌入互斥锁，即使该结构体未被导出。
|
||||
|
||||
```go
|
||||
// 不好：嵌入的互斥锁将 Lock/Unlock 暴露为 API 的一部分
|
||||
type SMap struct {
|
||||
sync.Mutex // Lock() 和 Unlock() 成为 SMap 的方法
|
||||
data map[string]string
|
||||
}
|
||||
|
||||
func (m *SMap) Get(k string) string {
|
||||
m.Lock()
|
||||
defer m.Unlock()
|
||||
return m.data[k]
|
||||
}
|
||||
```
|
||||
|
||||
```go
|
||||
// 好：命名字段使互斥锁保持为实现细节
|
||||
type SMap struct {
|
||||
mu sync.Mutex
|
||||
data map[string]string
|
||||
}
|
||||
|
||||
func (m *SMap) Get(k string) string {
|
||||
m.mu.Lock()
|
||||
defer m.mu.Unlock()
|
||||
return m.data[k]
|
||||
}
|
||||
```
|
||||
|
||||
在不好的示例中，`Lock` 和 `Unlock` 方法无意中成为了导出 API 的一部分。在好的示例中，互斥锁是对调用方隐藏的实现细节。
|
||||
|
||||
---
|
||||
|
||||
## 原子操作：完整示例
|
||||
|
||||
标准 `sync/atomic` 包操作原始类型（`int32`、`int64` 等），容易忘记一致地使用原子操作。
|
||||
|
||||
```go
|
||||
// 不好：容易忘记原子操作
|
||||
type foo struct {
|
||||
running int32 // 原子操作
|
||||
}
|
||||
|
||||
func (f *foo) start() {
|
||||
if atomic.SwapInt32(&f.running, 1) == 1 {
|
||||
return // 已在运行
|
||||
}
|
||||
// 启动 Foo
|
||||
}
|
||||
|
||||
func (f *foo) isRunning() bool {
|
||||
return f.running == 1 // 竞争！忘记使用 atomic.LoadInt32
|
||||
}
|
||||
```
|
||||
|
||||
```go
|
||||
// 好：类型安全的原子操作
|
||||
type foo struct {
|
||||
running atomic.Bool
|
||||
}
|
||||
|
||||
func (f *foo) start() {
|
||||
if f.running.Swap(true) {
|
||||
return // 已在运行
|
||||
}
|
||||
// 启动 Foo
|
||||
}
|
||||
|
||||
func (f *foo) isRunning() bool {
|
||||
return f.running.Load() // 不可能意外地非原子读取
|
||||
}
|
||||
```
|
||||
|
||||
`atomic.Bool`、`atomic.Int64` 等类型（Go 1.19 起在标准库 `sync/atomic` 中可用，或通过 [go.uber.org/atomic](https://pkg.go.dev/go.uber.org/atomic)）通过隐藏底层类型来增加类型安全性。
|
||||
|
||||
---
|
||||
|
||||
## Channel 方向示例
|
||||
|
||||
指定方向可以防止意外误用：
|
||||
|
||||
```go
|
||||
// 好：指定方向 - 清晰的所有权
|
||||
func sum(values <-chan int) int {
|
||||
total := 0
|
||||
for v := range values {
|
||||
total += v
|
||||
}
|
||||
return total
|
||||
}
|
||||
```
|
||||
|
||||
```go
|
||||
// 不好：未指定方向 - 允许意外误用
|
||||
func sum(values chan int) (out int) {
|
||||
for v := range values {
|
||||
out += v
|
||||
}
|
||||
close(values) // 漏洞！这能通过编译但不应该发生。
|
||||
}
|
||||
```
|
||||
@@ -1,122 +0,0 @@
|
||||
---
|
||||
name: go-context
|
||||
description: 在 Go 中使用 context.Context 时使用 — 包括函数签名中的位置、传播取消和截止时间、以及在 context 中存储值与使用参数的对比。也适用于取消长时间运行的操作、设置超时或传递请求作用域数据，即使未直接提及 context.Context。不涵盖 goroutine 生命周期或 sync 原语（参见 go-concurrency）。
|
||||
license: Apache-2.0
|
||||
compatibility: 需要 Go 1.7+（context 在 Go 1.7 中移入标准库）
|
||||
metadata:
|
||||
sources: "Go Wiki CodeReviewComments"
|
||||
---
|
||||
|
||||
# Go Context 用法
|
||||
|
||||
## Context 作为第一个参数
|
||||
|
||||
使用 Context 的函数应将其作为**第一个参数**：
|
||||
|
||||
```go
|
||||
func F(ctx context.Context, /* 其他参数 */) error
|
||||
func ProcessRequest(ctx context.Context, req *Request) (*Response, error)
|
||||
```
|
||||
|
||||
这是 Go 中的一个强约定，使 context 的传递在代码库中可见且一致。
|
||||
|
||||
---
|
||||
|
||||
## 不要在结构体中存储 Context
|
||||
|
||||
不要在结构体类型中添加 Context 成员。相反，将 `ctx` 作为参数传递给每个需要它的方法：
|
||||
|
||||
```go
|
||||
// 不好：Context 存储在结构体中
|
||||
type Worker struct {
|
||||
ctx context.Context // 不要这样做
|
||||
}
|
||||
|
||||
// 好：Context 传递给方法
|
||||
type Worker struct{ /* ... */ }
|
||||
|
||||
func (w *Worker) Process(ctx context.Context) error {
|
||||
// Context 显式传递 — 生命周期清晰
|
||||
}
|
||||
```
|
||||
|
||||
**例外**：签名必须匹配标准库或第三方库中接口的方法可能需要变通处理。
|
||||
|
||||
---
|
||||
|
||||
## 不要创建自定义 Context 类型
|
||||
|
||||
不要创建自定义的 Context 类型或在函数签名中使用 `context.Context` 以外的接口：
|
||||
|
||||
```go
|
||||
// 不好：自定义 context 类型
|
||||
type MyContext interface {
|
||||
context.Context
|
||||
GetUserID() string
|
||||
}
|
||||
|
||||
// 好：使用标准 context.Context 并提取值
|
||||
func Process(ctx context.Context) error {
|
||||
userID := GetUserID(ctx)
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 应用数据放在哪里
|
||||
|
||||
按以下优先级顺序考虑：
|
||||
|
||||
1. **函数参数** — 最明确且类型安全
|
||||
2. **接收者** — 适用于属于该类型的数据
|
||||
3. **全局变量** — 适用于真正的全局配置（谨慎使用）
|
||||
4. **Context 值** — 仅用于请求作用域数据
|
||||
|
||||
Context 值适用于：
|
||||
- 请求 ID 和追踪 ID
|
||||
- 随请求流动的认证/授权信息
|
||||
- 截止时间和取消信号
|
||||
|
||||
Context 值**不适用**于：
|
||||
- 可选的函数参数
|
||||
- 可以显式传递的数据
|
||||
- 不随请求变化的配置
|
||||
|
||||
---
|
||||
|
||||
## 常见模式
|
||||
|
||||
> 在派生 context（WithTimeout、WithCancel、WithDeadline）、在循环或 HTTP 处理器中检查取消、使用带类型键的 context 值、或需要快速参考表时，阅读 [references/PATTERNS.md](references/PATTERNS.md)。
|
||||
|
||||
### 派生 Context
|
||||
|
||||
创建派生 context 后，始终立即 `defer cancel()`：
|
||||
|
||||
```go
|
||||
ctx, cancel := context.WithTimeout(ctx, 5*time.Second)
|
||||
defer cancel()
|
||||
```
|
||||
|
||||
### 检查取消
|
||||
|
||||
```go
|
||||
select {
|
||||
case <-ctx.Done():
|
||||
return ctx.Err()
|
||||
default:
|
||||
// 执行工作
|
||||
}
|
||||
```
|
||||
|
||||
### Context 不可变性
|
||||
|
||||
Context 是不可变的 — 将同一个 `ctx` 传递给共享相同截止时间和取消信号的多个并发调用是安全的。
|
||||
|
||||
---
|
||||
|
||||
## 相关技能
|
||||
|
||||
- **Goroutine 协调**：在使用 context 进行 goroutine 取消、基于 select 的超时或 errgroup 时，参见 [go-concurrency](../go-concurrency/SKILL.md)
|
||||
- **错误处理**：在决定如何包装或返回 `ctx.Err()` 取消错误时，参见 [go-error-handling](../go-error-handling/SKILL.md)
|
||||
- **接口设计**：在设计接受 context 并结合接口的 API 时，参见 [go-interfaces](../go-interfaces/SKILL.md)
|
||||
- **请求作用域日志**：在将 logger 注入 context 或将请求 ID 添加到结构化日志输出时，参见 [go-logging](../go-logging/SKILL.md)
|
||||
@@ -1,227 +0,0 @@
|
||||
# Context 模式
|
||||
|
||||
派生、检查和传播 `context.Context` 的常见模式。
|
||||
|
||||
---
|
||||
|
||||
## Context 不可变性
|
||||
|
||||
Context 是不可变的。将同一个 `ctx` 传递给共享相同截止时间、取消信号、凭据和父级追踪的多个调用是安全的：
|
||||
|
||||
```go
|
||||
// 安全：同一个 context 传递给顺序调用
|
||||
func ProcessBatch(ctx context.Context, items []Item) error {
|
||||
for _, item := range items {
|
||||
if err := process(ctx, item); err != nil {
|
||||
return err
|
||||
}
|
||||
}
|
||||
return nil
|
||||
}
|
||||
|
||||
// 安全：同一个 context 传递给并发调用
|
||||
func ProcessConcurrently(ctx context.Context, a, b *Data) error {
|
||||
g, ctx := errgroup.WithContext(ctx)
|
||||
g.Go(func() error { return processA(ctx, a) })
|
||||
g.Go(func() error { return processB(ctx, b) })
|
||||
return g.Wait()
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 何时使用 context.Background()
|
||||
|
||||
仅在**从不特定于请求**的函数中使用 `context.Background()`：
|
||||
|
||||
```go
|
||||
func main() {
|
||||
ctx := context.Background()
|
||||
if err := run(ctx); err != nil {
|
||||
log.Fatal(err)
|
||||
}
|
||||
}
|
||||
|
||||
func startBackgroundWorker() {
|
||||
ctx := context.Background()
|
||||
go worker(ctx)
|
||||
}
|
||||
```
|
||||
|
||||
**默认传递 Context**，即使你认为不需要。只有在有充分理由说明传递 context 是错误做法时，才直接使用 `context.Background()`：
|
||||
|
||||
```go
|
||||
func LoadConfig(ctx context.Context) (*Config, error) {
|
||||
// 即使现在不使用 ctx，接受它可以在未来添加功能时
|
||||
// 不需要修改 API
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 派生 Context
|
||||
|
||||
```go
|
||||
// 添加超时 — 持续时间结束后触发取消
|
||||
ctx, cancel := context.WithTimeout(ctx, 5*time.Second)
|
||||
defer cancel()
|
||||
|
||||
// 添加取消 — 调用者控制何时取消
|
||||
ctx, cancel := context.WithCancel(ctx)
|
||||
defer cancel()
|
||||
|
||||
// 添加截止时间 — 在指定的墙钟时间触发取消
|
||||
ctx, cancel := context.WithDeadline(ctx, time.Now().Add(time.Hour))
|
||||
defer cancel()
|
||||
|
||||
// 添加值（谨慎使用 — 仅用于请求作用域数据）
|
||||
ctx = context.WithValue(ctx, requestIDKey, reqID)
|
||||
```
|
||||
|
||||
创建派生 context 后，**始终立即 `defer cancel()`**。这确保即使函数提前返回，资源也会被释放。
|
||||
|
||||
### 嵌套派生
|
||||
|
||||
派生的 context 形成树状结构。取消父级会取消所有子级：
|
||||
|
||||
```go
|
||||
func handleRequest(ctx context.Context) error {
|
||||
// 整个请求的父级超时
|
||||
ctx, cancel := context.WithTimeout(ctx, 30*time.Second)
|
||||
defer cancel()
|
||||
|
||||
// 数据库调用的更短超时
|
||||
dbCtx, dbCancel := context.WithTimeout(ctx, 5*time.Second)
|
||||
defer dbCancel()
|
||||
|
||||
data, err := queryDB(dbCtx)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
|
||||
// 父级 context 的剩余时间适用于此处
|
||||
return sendResponse(ctx, data)
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 检查取消
|
||||
|
||||
### 在长时间运行的循环中
|
||||
|
||||
```go
|
||||
func LongRunningOperation(ctx context.Context) error {
|
||||
for {
|
||||
select {
|
||||
case <-ctx.Done():
|
||||
return ctx.Err()
|
||||
default:
|
||||
// 执行工作
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 在高开销操作之前
|
||||
|
||||
在开始无法中断的工作之前检查取消：
|
||||
|
||||
```go
|
||||
func ProcessItems(ctx context.Context, items []Item) error {
|
||||
for _, item := range items {
|
||||
if ctx.Err() != nil {
|
||||
return ctx.Err()
|
||||
}
|
||||
if err := expensiveProcess(item); err != nil {
|
||||
return err
|
||||
}
|
||||
}
|
||||
return nil
|
||||
}
|
||||
```
|
||||
|
||||
### 区分取消原因
|
||||
|
||||
```go
|
||||
if err := ctx.Err(); err != nil {
|
||||
switch {
|
||||
case errors.Is(err, context.Canceled):
|
||||
// 调用者显式取消（例如客户端断开连接）
|
||||
case errors.Is(err, context.DeadlineExceeded):
|
||||
// 超时或截止时间已过
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 在 HTTP 处理器中遵守取消
|
||||
|
||||
```go
|
||||
func handler(w http.ResponseWriter, r *http.Request) {
|
||||
ctx := r.Context()
|
||||
|
||||
result, err := slowOperation(ctx)
|
||||
if err != nil {
|
||||
if errors.Is(err, context.Canceled) {
|
||||
// 客户端已断开连接 — 无需写入
|
||||
return
|
||||
}
|
||||
http.Error(w, err.Error(), http.StatusInternalServerError)
|
||||
return
|
||||
}
|
||||
|
||||
json.NewEncoder(w).Encode(result)
|
||||
}
|
||||
```
|
||||
|
||||
`r.Context()` 在以下情况被取消：
|
||||
- 客户端关闭连接
|
||||
- `http.Server` 的 `ReadTimeout` 或 `WriteTimeout` 触发
|
||||
- `ServeHTTP` 方法返回
|
||||
|
||||
---
|
||||
|
||||
## Context 值的最佳实践
|
||||
|
||||
### 使用未导出的键类型
|
||||
|
||||
```go
|
||||
type contextKey struct{}
|
||||
|
||||
var userIDKey contextKey
|
||||
|
||||
func WithUserID(ctx context.Context, id string) context.Context {
|
||||
return context.WithValue(ctx, userIDKey, id)
|
||||
}
|
||||
|
||||
func UserIDFromContext(ctx context.Context) (string, bool) {
|
||||
id, ok := ctx.Value(userIDKey).(string)
|
||||
return id, ok
|
||||
}
|
||||
```
|
||||
|
||||
使用未导出的结构体类型作为键可以防止与其他包的键发生冲突 — 即使它们使用相同的 string 或 int 值。
|
||||
|
||||
### 提供访问器函数
|
||||
|
||||
始终将 `context.WithValue` 和 `ctx.Value` 包装在类型化的辅助函数中（如上所示），而不是暴露键。这提供了类型安全性和一个可以修改实现的单一位置。
|
||||
|
||||
---
|
||||
|
||||
## 快速参考
|
||||
|
||||
| 模式 | 指导 |
|
||||
|------|------|
|
||||
| 参数位置 | 始终第一个：`func F(ctx context.Context, ...)` |
|
||||
| 结构体存储 | 不要存储在结构体中；传递给方法 |
|
||||
| 自定义类型 | 不要创建；使用 `context.Context` 接口 |
|
||||
| 应用数据 | 优先选择 参数 > 接收者 > 全局变量 > context 值 |
|
||||
| 请求作用域数据 | 适用于 context 值 |
|
||||
| 共享 context | 安全 — context 是不可变的 |
|
||||
| `context.Background()` | 仅用于非请求特定的代码 |
|
||||
| 默认行为 | 即使认为不需要也要传递 context |
|
||||
| `defer cancel()` | 在 `WithTimeout`/`WithCancel`/`WithDeadline` 之后始终立即 defer |
|
||||
| 值键 | 使用未导出的结构体类型，提供访问器函数 |
|
||||
| 取消检查 | 在高开销操作前使用 `ctx.Err()`；在循环中使用 `select` 监听 `ctx.Done()` |
|
||||
@@ -1,193 +0,0 @@
|
||||
---
|
||||
name: go-control-flow
|
||||
description: Use when writing conditionals, loops, or switch statements in Go — including if with initialization, early returns, for loop forms, range, switch, type switches, and blank identifier patterns. Also use when writing a simple if/else or for loop, even if the user doesn't mention guard clauses or variable scoping. Does not cover error flow patterns (see go-error-handling).
|
||||
license: Apache-2.0
|
||||
metadata:
|
||||
sources: "Effective Go, Google Style Guide"
|
||||
---
|
||||
|
||||
# Go 控制流
|
||||
|
||||
> 在使用 switch 语句、类型 switch 或带标签的 break 时，阅读 [references/SWITCH-PATTERNS.md](references/SWITCH-PATTERNS.md)
|
||||
|
||||
> 在使用 `_`、空白标识符导入或编译时接口检查时，阅读 [references/BLANK-IDENTIFIER.md](references/BLANK-IDENTIFIER.md)
|
||||
|
||||
---
|
||||
|
||||
## 带初始化的 If
|
||||
|
||||
`if` 和 `switch` 接受可选的初始化语句。使用它将变量限定在条件块作用域内：
|
||||
|
||||
```go
|
||||
if err := file.Chmod(0664); err != nil {
|
||||
log.Print(err)
|
||||
return err
|
||||
}
|
||||
```
|
||||
|
||||
如果需要在 `if` 之后超出几行的范围使用该变量，请单独声明并使用标准 `if`：
|
||||
|
||||
```go
|
||||
x, err := f()
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
// 大量使用 x 的代码
|
||||
```
|
||||
|
||||
## 缩进错误流（守卫子句）
|
||||
|
||||
当 `if` 主体以 `break`、`continue`、`goto` 或 `return` 结尾时，省略不必要的 `else`。保持成功路径不缩进：
|
||||
|
||||
```go
|
||||
f, err := os.Open(name)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
d, err := f.Stat()
|
||||
if err != nil {
|
||||
f.Close()
|
||||
return err
|
||||
}
|
||||
codeUsing(f, d)
|
||||
```
|
||||
|
||||
当 `if` 已经返回时，绝不要将正常流程埋在 `else` 中。
|
||||
|
||||
---
|
||||
|
||||
## 重新声明和重新赋值
|
||||
|
||||
`:=` 短声明允许在同一作用域中重新声明变量：
|
||||
|
||||
```go
|
||||
f, err := os.Open(name) // 声明 f 和 err
|
||||
d, err := f.Stat() // 声明 d，重新赋值 err
|
||||
```
|
||||
|
||||
变量 `v` 即使已经声明过，也可以出现在 `:=` 声明中，前提是：
|
||||
|
||||
1. 声明在与现有 `v` **相同的作用域**中
|
||||
2. 值**可赋值**给 `v`
|
||||
3. 声明中至少创建了**一个其他新变量**
|
||||
|
||||
### 变量遮蔽
|
||||
|
||||
**警告**：如果 `v` 在外层作用域中声明，`:=` 会创建一个**新的**遮蔽变量 — 这是常见的 bug 来源：
|
||||
|
||||
```go
|
||||
// Bug：if 块内的 ctx 遮蔽了外层的 ctx
|
||||
if *shortenDeadlines {
|
||||
ctx, cancel := context.WithTimeout(ctx, 3*time.Second)
|
||||
defer cancel()
|
||||
}
|
||||
// 此处的 ctx 仍然是原始的 — 被遮蔽的 ctx 没有逃逸
|
||||
|
||||
// 修复：使用 = 而不是 :=
|
||||
var cancel func()
|
||||
ctx, cancel = context.WithTimeout(ctx, 3*time.Second)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## For 循环
|
||||
|
||||
Go 的 `for` 是唯一的循环结构，统一了 `while`、`do-while` 和 C 风格的 `for`：
|
||||
|
||||
```go
|
||||
// 仅条件（Go 的 "while"）
|
||||
for x > 0 {
|
||||
x = process(x)
|
||||
}
|
||||
|
||||
// 无限循环
|
||||
for {
|
||||
if done() { break }
|
||||
}
|
||||
|
||||
// C 风格的三组件形式
|
||||
for i := 0; i < n; i++ { ... }
|
||||
```
|
||||
|
||||
### Range
|
||||
|
||||
`range` 遍历切片、映射、字符串和通道：
|
||||
|
||||
```go
|
||||
for i, v := range slice { ... } // 索引 + 值
|
||||
for k, v := range myMap { ... } // 键 + 值（顺序不确定）
|
||||
for i, r := range "héllo" { ... } // 字节索引 + rune（不是字节）
|
||||
for v := range ch { ... } // 接收直到通道关闭
|
||||
```
|
||||
|
||||
**关键规则：**
|
||||
- 对字符串 range 产生 **rune**，不是字节 — `i` 是字节偏移量
|
||||
- 对映射 range 的顺序**不确定** — 不要依赖它
|
||||
- 使用 `_` 丢弃索引或值：`for _, v := range slice`
|
||||
|
||||
### 并行赋值
|
||||
|
||||
Go 没有逗号运算符。使用并行赋值处理多个循环变量：
|
||||
|
||||
```go
|
||||
for i, j := 0, len(a)-1; i < j; i, j = i+1, j-1 {
|
||||
a[i], a[j] = a[j], a[i]
|
||||
}
|
||||
```
|
||||
|
||||
`++` 和 `--` 是语句，不是表达式 — 它们不能出现在并行赋值中。
|
||||
|
||||
---
|
||||
|
||||
## Switch：带标签的 Break
|
||||
|
||||
`for` 循环内 `switch` 中的 `break` 只会中断 switch。使用带标签的 `break` 退出外层循环：
|
||||
|
||||
```go
|
||||
Loop:
|
||||
for _, v := range items {
|
||||
switch v.Type {
|
||||
case "done":
|
||||
break Loop // 中断 for 循环
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
关于类型 switch，参见 **go-interfaces**：类型 Switch。
|
||||
|
||||
---
|
||||
|
||||
## 空白标识符
|
||||
|
||||
**绝不要随意丢弃错误** — 空指针解引用 panic 可能随之而来。
|
||||
|
||||
在编译时验证接口实现：`var _ io.Writer = (*MyType)(nil)`。
|
||||
参见 **go-interfaces** 中的接口满足检查模式。
|
||||
|
||||
---
|
||||
|
||||
## 快速参考
|
||||
|
||||
| 模式 | Go 惯用法 |
|
||||
|------|-----------|
|
||||
| If 初始化 | `if err := f(); err != nil { }` |
|
||||
| 提前返回 | 当 if 主体返回时省略 `else` |
|
||||
| 重新声明 | `:=` 在相同作用域 + 新变量时重新赋值 |
|
||||
| 遮蔽陷阱 | `:=` 在内层作用域创建新变量 |
|
||||
| 并行赋值 | `i, j = i+1, j-1` |
|
||||
| 无表达式 switch | `switch { case cond: }` |
|
||||
| 逗号 case | `case 'a', 'b', 'c':` |
|
||||
| 无 fallthrough | 默认行为（需要时显式使用 `fallthrough`） |
|
||||
| 从 switch 中跳出循环 | `break Label` |
|
||||
| 丢弃值 | `_, err := f()` |
|
||||
| 副作用导入 | `import _ "pkg"` |
|
||||
| 接口检查 | `var _ Interface = (*Type)(nil)` |
|
||||
|
||||
---
|
||||
|
||||
## 相关技能
|
||||
|
||||
- **错误流程**：在构建守卫子句、提前返回或错误优先模式时，参见 [go-error-handling](../go-error-handling/SKILL.md)
|
||||
- **类型 switch**：在使用类型 switch、comma-ok 惯用法或接口满足检查时，参见 [go-interfaces](../go-interfaces/SKILL.md)
|
||||
- **减少嵌套**：在减少嵌套深度或解决格式问题时，参见 [go-style-core](../go-style-core/SKILL.md)
|
||||
- **变量作用域**：在使用 if 初始化、`:=` 重新声明或减少变量作用域时，参见 [go-declarations](../go-declarations/SKILL.md)
|
||||
@@ -1,71 +0,0 @@
|
||||
# 空白标识符模式
|
||||
|
||||
空白标识符 `_` 在 Go 中有多种用途：丢弃不需要的值、为副作用导入包、以及在编译时验证接口实现。
|
||||
|
||||
---
|
||||
|
||||
## 多重赋值
|
||||
|
||||
使用 `_` 丢弃多值表达式中不需要的值：
|
||||
|
||||
```go
|
||||
if _, err := os.Stat(path); os.IsNotExist(err) {
|
||||
fmt.Printf("%s does not exist\n", path)
|
||||
}
|
||||
```
|
||||
|
||||
### 绝不要随意丢弃错误
|
||||
|
||||
静默丢弃错误会引发空指针 panic：
|
||||
|
||||
```go
|
||||
// 不好：忽略错误会在路径不存在时崩溃
|
||||
fi, _ := os.Stat(path)
|
||||
if fi.IsDir() { ... } // 空指针解引用
|
||||
```
|
||||
|
||||
如果确实不需要错误，请记录原因：
|
||||
|
||||
```go
|
||||
_ = logger.Sync() // 尽力刷新；错误不可操作
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 副作用导入
|
||||
|
||||
使用空白标识符仅为了 `init()` 副作用而导入包：
|
||||
|
||||
```go
|
||||
import _ "net/http/pprof" // 注册 HTTP 处理器
|
||||
import _ "image/png" // 注册 PNG 解码器
|
||||
```
|
||||
|
||||
这通常用于注册驱动、编解码器或调试处理器，它们在 `init()` 期间将自己注册到注册表中。
|
||||
|
||||
---
|
||||
|
||||
## 接口实现检查
|
||||
|
||||
在编译时验证类型是否实现了接口，方法是将 nil 指针赋值给接口类型的空白标识符变量：
|
||||
|
||||
```go
|
||||
var _ io.Writer = (*MyType)(nil)
|
||||
```
|
||||
|
||||
如果 `*MyType` 不满足 `io.Writer`，这会产生编译错误，在运行时之前捕获缺失的方法。
|
||||
|
||||
**何时使用**：将此检查放在定义该类型的同一文件中，通常在类型声明之后。当类型必须满足另一个包中定义的接口时特别有用。
|
||||
|
||||
参见 [go-interfaces](../../go-interfaces/SKILL.md)：接口满足检查，获取关于何时何地使用此模式的完整指导。
|
||||
|
||||
---
|
||||
|
||||
## 快速参考
|
||||
|
||||
| 模式 | 语法 |
|
||||
|------|------|
|
||||
| 丢弃值 | `_, err := f()` |
|
||||
| 在 if 初始化中丢弃 | `if _, err := f(); err != nil { }` |
|
||||
| 副作用导入 | `import _ "pkg"` |
|
||||
| 接口检查 | `var _ Interface = (*Type)(nil)` |
|
||||
@@ -1,109 +0,0 @@
|
||||
# Switch 模式
|
||||
|
||||
Go `switch` 语句的详细模式，包括无表达式 switch、逗号 case、break 行为和带标签的 break。
|
||||
|
||||
---
|
||||
|
||||
## 无自动 Fallthrough
|
||||
|
||||
Go `switch` 的 case 默认**不会** fall through（与 C/Java 不同）。每个 case 主体隐式地 break。仅在明确需要时使用 `fallthrough` — 这在惯用 Go 中很少见。
|
||||
|
||||
```go
|
||||
switch n {
|
||||
case 1:
|
||||
fmt.Println("one")
|
||||
// 无 fallthrough — 下一个 case 不会执行
|
||||
case 2:
|
||||
fmt.Println("two")
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 无表达式 Switch
|
||||
|
||||
没有表达式的 `switch` 对 `true` 进行 switch。在将单个变量与多个条件进行比较时，用它来替代 if-else-if 链：
|
||||
|
||||
```go
|
||||
func unhex(c byte) byte {
|
||||
switch {
|
||||
case '0' <= c && c <= '9':
|
||||
return c - '0'
|
||||
case 'a' <= c && c <= 'f':
|
||||
return c - 'a' + 10
|
||||
case 'A' <= c && c <= 'F':
|
||||
return c - 'A' + 10
|
||||
}
|
||||
return 0
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 逗号分隔的 Case
|
||||
|
||||
多个值可以使用逗号共享一个 case 主体 — 不需要 `fallthrough`：
|
||||
|
||||
```go
|
||||
func shouldEscape(c byte) bool {
|
||||
switch c {
|
||||
case ' ', '?', '&', '=', '#', '+', '%':
|
||||
return true
|
||||
}
|
||||
return false
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 带标签的 Break
|
||||
|
||||
`switch` 中的 `break` 仅终止 switch，**不会**终止外层的 `for` 循环。使用标签来跳出循环：
|
||||
|
||||
```go
|
||||
Loop:
|
||||
for n := 0; n < len(src); n += size {
|
||||
switch {
|
||||
case src[n] < sizeOne:
|
||||
break // 仅中断 switch
|
||||
case src[n] < sizeTwo:
|
||||
if n+1 >= len(src) {
|
||||
break Loop // 跳出 for 循环
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
另一个常见模式 — 从 switch 内部中断 range 循环：
|
||||
|
||||
```go
|
||||
Loop:
|
||||
for _, v := range items {
|
||||
switch v.Type {
|
||||
case "done":
|
||||
break Loop // 中断 for 循环
|
||||
case "skip":
|
||||
break // 仅中断 switch
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**经验法则**：当 `for` 循环内有 `switch` 且需要从 case 中退出循环时，始终使用带标签的 break。
|
||||
|
||||
---
|
||||
|
||||
## 类型 Switch
|
||||
|
||||
关于类型 switch（`switch v := x.(type)`），参见 [go-interfaces](../../go-interfaces/SKILL.md)：类型 Switch。
|
||||
|
||||
---
|
||||
|
||||
## 快速参考
|
||||
|
||||
| 模式 | 语法 |
|
||||
|------|------|
|
||||
| 无表达式 switch | `switch { case cond: }` |
|
||||
| 逗号 case | `case 'a', 'b', 'c':` |
|
||||
| 无 fallthrough | 默认行为；需要时使用 `fallthrough` 关键字 |
|
||||
| 仅中断 switch | case 内使用 `break` |
|
||||
| 中断外层循环 | 使用带标签的 `for` 和 `break Label` |
|
||||
@@ -1,140 +0,0 @@
|
||||
---
|
||||
name: go-data-structures
|
||||
description: Use when working with Go slices, maps, or arrays — choosing between new and make, using append, declaring empty slices (nil vs literal for JSON), implementing sets with maps, and copying data at boundaries. Also use when building or manipulating collections, even if the user doesn't ask about allocation idioms. Does not cover concurrent data structure safety (see go-concurrency).
|
||||
license: Apache-2.0
|
||||
metadata:
|
||||
sources: "Effective Go, Google Style Guide, Uber Style Guide, Go Wiki CodeReviewComments"
|
||||
---
|
||||
|
||||
# Go 数据结构
|
||||
|
||||
---
|
||||
|
||||
## 选择数据结构
|
||||
|
||||
```
|
||||
你需要什么？
|
||||
├─ 有序的元素集合
|
||||
│ ├─ 编译时已知固定大小 → 数组 [N]T
|
||||
│ └─ 动态大小 → 切片 []T
|
||||
│ ├─ 知道大概的大小？→ make([]T, 0, capacity)
|
||||
│ └─ 未知大小或需要 nil 安全的 JSON？→ var s []T (nil)
|
||||
├─ 键值查找
|
||||
│ └─ 映射 map[K]V
|
||||
│ ├─ 知道大概的大小？→ make(map[K]V, capacity)
|
||||
│ └─ 需要集合？→ map[T]struct{}（零大小值）
|
||||
└─ 需要传递给函数？
|
||||
└─ 如果调用者可能会修改它，则在边界处复制
|
||||
```
|
||||
|
||||
> **此技能不适用的场景**：对于数据结构的并发访问（互斥锁、原子操作），参见 [go-concurrency](../go-concurrency/SKILL.md)。对于 API 边界处的防御性复制，参见 [go-defensive](../go-defensive/SKILL.md)。对于为性能预分配容量，参见 [go-performance](../go-performance/SKILL.md)。
|
||||
|
||||
---
|
||||
|
||||
## 切片
|
||||
|
||||
### append 函数
|
||||
|
||||
**始终赋值结果** — 底层数组可能会改变：
|
||||
|
||||
```go
|
||||
x := []int{1, 2, 3}
|
||||
x = append(x, 4, 5, 6)
|
||||
|
||||
// 将切片追加到切片
|
||||
x = append(x, y...) // 注意 ...
|
||||
```
|
||||
|
||||
### 二维切片
|
||||
|
||||
**独立的内部切片**（可以独立增长/缩小）：
|
||||
|
||||
```go
|
||||
picture := make([][]uint8, YSize)
|
||||
for i := range picture {
|
||||
picture[i] = make([]uint8, XSize)
|
||||
}
|
||||
```
|
||||
|
||||
**单次分配**（对于固定大小更高效）：
|
||||
|
||||
```go
|
||||
picture := make([][]uint8, YSize)
|
||||
pixels := make([]uint8, XSize*YSize)
|
||||
for i := range picture {
|
||||
picture[i], pixels = pixels[:XSize], pixels[XSize:]
|
||||
}
|
||||
```
|
||||
|
||||
> 在调试意外的切片行为、跨 goroutine 共享切片或处理切片头时，阅读 [references/SLICES.md](references/SLICES.md)。
|
||||
|
||||
### 声明空切片
|
||||
|
||||
优先使用 nil 切片而非空字面量：
|
||||
|
||||
```go
|
||||
// 好：nil 切片
|
||||
var t []string
|
||||
|
||||
// 避免：非 nil 但零长度
|
||||
t := []string{}
|
||||
```
|
||||
|
||||
两者的 `len` 和 `cap` 都是零，但 nil 切片是首选风格。
|
||||
|
||||
**JSON 例外**：nil 切片编码为 `null`，而 `[]string{}` 编码为 `[]`。当需要 JSON 数组时使用非 nil。
|
||||
|
||||
在设计接口时，避免区分 nil 和非 nil 的零长度切片。
|
||||
|
||||
---
|
||||
|
||||
## 映射
|
||||
|
||||
### 实现集合
|
||||
|
||||
使用 `map[T]bool` — 惯用且阅读自然：
|
||||
|
||||
```go
|
||||
attended := map[string]bool{"Ann": true, "Joe": true}
|
||||
if attended[person] { // 不在映射中则为 false
|
||||
fmt.Println(person, "was at the meeting")
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 复制
|
||||
|
||||
从另一个包复制结构体时要小心。如果类型的方法定义在指针类型（`*T`）上，复制值可能导致别名 bug。
|
||||
|
||||
**通用规则：** 如果类型 `T` 的方法与指针类型 `*T` 关联，则不要复制 `T` 的值。这适用于 `bytes.Buffer`、`sync.Mutex`、`sync.WaitGroup` 以及包含它们的类型。
|
||||
|
||||
```go
|
||||
// 不好：复制互斥锁
|
||||
var mu sync.Mutex
|
||||
mu2 := mu // 几乎总是 bug
|
||||
|
||||
// 好：通过指针传递
|
||||
func increment(sc *SafeCounter) {
|
||||
sc.mu.Lock()
|
||||
sc.count++
|
||||
sc.mu.Unlock()
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 快速参考
|
||||
|
||||
| 主题 | 关键点 |
|
||||
|------|--------|
|
||||
| 切片 | 始终赋值 `append` 结果；`nil` 切片优于 `[]T{}` |
|
||||
| 集合 | `map[T]bool` 是惯用写法 |
|
||||
| 复制 | 如果方法在 `*T` 上则不要复制 `T`；注意别名问题 |
|
||||
|
||||
## 相关技能
|
||||
|
||||
- **防御性复制**：在 API 边界处复制切片或映射以防止修改时，参见 [go-defensive](../go-defensive/SKILL.md)
|
||||
- **容量提示**：为已知工作负载预分配切片或映射容量时，参见 [go-performance](../go-performance/SKILL.md)
|
||||
- **迭代模式**：在对切片、映射或通道使用 range 循环时，参见 [go-control-flow](../go-control-flow/SKILL.md)
|
||||
- **声明风格**：在 `new`、`make`、`var` 和复合字面量之间选择时，参见 [go-declarations](../go-declarations/SKILL.md)
|
||||
@@ -1,146 +0,0 @@
|
||||
# Go 切片内部原理
|
||||
|
||||
> **来源**：Effective Go
|
||||
|
||||
---
|
||||
|
||||
## 三项描述符
|
||||
|
||||
切片是一个运行时数据结构，包含三个组件：
|
||||
|
||||
- **指针**：第一个可访问元素的地址
|
||||
- **长度**：元素数量（`len(s)`）
|
||||
- **容量**：到底层数组末尾的最大元素数（`cap(s)`）
|
||||
|
||||
```go
|
||||
arr := [5]int{10, 20, 30, 40, 50}
|
||||
s := arr[1:4] // s = [20, 30, 40]
|
||||
// 指针：&arr[1]，长度：3，容量：4
|
||||
```
|
||||
|
||||
`nil` 切片的三项均为零/nil。
|
||||
|
||||
---
|
||||
|
||||
## 切片引用底层数组
|
||||
|
||||
切片不存储数据 — 它们描述数组的一部分：
|
||||
|
||||
```go
|
||||
data := [4]int{1, 2, 3, 4}
|
||||
a := data[0:2] // [1, 2]
|
||||
b := data[1:3] // [2, 3]
|
||||
|
||||
b[0] = 99
|
||||
fmt.Println(a) // [1, 99] - 两者都看到变化
|
||||
fmt.Println(data) // [1, 99, 3, 4]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 切片运算符
|
||||
|
||||
`s[lo:hi]` 创建从索引 `lo` 到 `hi-1` 的切片：
|
||||
|
||||
```go
|
||||
s := []int{0, 1, 2, 3, 4, 5}
|
||||
s[2:4] // [2, 3]
|
||||
s[:3] // [0, 1, 2]
|
||||
s[3:] // [3, 4, 5]
|
||||
```
|
||||
|
||||
三索引形式 `s[lo:hi:max]` 将容量限制为 `max-lo`。
|
||||
|
||||
---
|
||||
|
||||
## 为什么 append 必须返回切片
|
||||
|
||||
切片头是**按值传递**的。函数可以修改元素但无法改变调用者的切片头：
|
||||
|
||||
```go
|
||||
func Append(slice, data []byte) []byte {
|
||||
l := len(slice)
|
||||
if l+len(data) > cap(slice) {
|
||||
newSlice := make([]byte, (l+len(data))*2)
|
||||
copy(newSlice, slice)
|
||||
slice = newSlice // 只改变局部变量
|
||||
}
|
||||
slice = slice[0 : l+len(data)]
|
||||
copy(slice[l:], data)
|
||||
return slice // 调用者必须接收新的切片头
|
||||
}
|
||||
```
|
||||
|
||||
当发生重新分配时，`slice` 指向新数组。调用者的原始引用仍指向旧数组 — 返回使调用者能够更新其引用。
|
||||
|
||||
---
|
||||
|
||||
## copy 函数
|
||||
|
||||
`copy(dst, src)` 复制元素并返回复制的数量：
|
||||
|
||||
```go
|
||||
src := []int{1, 2, 3, 4, 5}
|
||||
dst := make([]int, 3)
|
||||
n := copy(dst, src) // n=3, dst=[1,2,3]
|
||||
```
|
||||
|
||||
正确处理重叠切片。复制 `min(len(dst), len(src))` 个元素 — 不会发生重新分配。
|
||||
|
||||
---
|
||||
|
||||
## 切片常见陷阱
|
||||
|
||||
### 1. 共享底层数组
|
||||
|
||||
```go
|
||||
original := []int{1, 2, 3, 4, 5}
|
||||
subset := original[1:3]
|
||||
subset[0] = 99
|
||||
fmt.Println(original) // [1, 99, 3, 4, 5] - 被修改了！
|
||||
|
||||
// 修复：创建独立副本
|
||||
subset := make([]int, 2)
|
||||
copy(subset, original[1:3])
|
||||
```
|
||||
|
||||
### 2. append 可能重新分配也可能不
|
||||
|
||||
```go
|
||||
a := make([]int, 3, 5) // len=3, cap=5
|
||||
b := a[0:3]
|
||||
a = append(a, 4) // 在容量内 - 仍然共享
|
||||
a = append(a, 5, 6) // 超出容量 - 现在独立
|
||||
```
|
||||
|
||||
### 3. 大底层数组导致内存泄漏
|
||||
|
||||
```go
|
||||
// 不好：小切片将整个文件保留在内存中
|
||||
func getHeader(file []byte) []byte { return file[:100] }
|
||||
|
||||
// 好：复制以释放大数组
|
||||
func getHeader(file []byte) []byte {
|
||||
header := make([]byte, 100)
|
||||
copy(header, file)
|
||||
return header
|
||||
}
|
||||
```
|
||||
|
||||
### 4. nil vs 空切片
|
||||
|
||||
```go
|
||||
var nilSlice []int // nil, len=0, cap=0
|
||||
emptySlice := []int{} // 非 nil, len=0, cap=0
|
||||
// 两者在 len、cap、append、range 中表现相同
|
||||
// 未初始化状态优先使用 nil
|
||||
```
|
||||
|
||||
## 快速参考
|
||||
|
||||
| 操作 | 行为 |
|
||||
|------|------|
|
||||
| `s[lo:hi]` | 从 lo 到 hi-1 的切片 |
|
||||
| `s[lo:hi:max]` | 容量限制为 max-lo 的切片 |
|
||||
| `append(s, x...)` | 返回新切片；可能重新分配 |
|
||||
| `copy(dst, src)` | 返回复制数量；不重新分配 |
|
||||
@@ -1,188 +0,0 @@
|
||||
---
|
||||
name: go-defensive
|
||||
description: Use when hardening Go code at API boundaries — copying slices/maps, verifying interface compliance, using defer for cleanup, time.Time/time.Duration, or avoiding mutable globals. Also use when reviewing for robustness concerns like missing cleanup or unsafe crypto usage, even if the user doesn't mention "defensive programming." Does not cover error handling strategy (see go-error-handling).
|
||||
license: Apache-2.0
|
||||
compatibility: Uses crypto/rand.Text (Go 1.24+) in examples
|
||||
metadata:
|
||||
sources: "Effective Go, Uber Style Guide, Go Wiki CodeReviewComments"
|
||||
---
|
||||
|
||||
# Go 防御性编程模式
|
||||
|
||||
## 防御性检查清单优先级
|
||||
|
||||
在加固 API 边界代码时，按以下顺序检查：
|
||||
|
||||
```
|
||||
正在审查 API 边界？
|
||||
├─ 1. 错误处理 → 返回错误；不要 panic（参见 go-error-handling）
|
||||
├─ 2. 输入验证 → 复制从调用者接收的切片/map
|
||||
├─ 3. 输出安全 → 在返回给调用者之前复制切片/map
|
||||
├─ 4. 资源清理 → 使用 defer 进行 Close/Unlock/Cancel
|
||||
├─ 5. 接口检查 → var _ Interface = (*Type)(nil) 编译时验证
|
||||
├─ 6. 时间正确性 → 使用 time.Time 和 time.Duration，不要用 int/float
|
||||
├─ 7. 枚举安全 → iota 从 1 开始，使零值无效
|
||||
└─ 8. 加密安全 → 用 crypto/rand 生成密钥，绝不用 math/rand
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 快速参考
|
||||
|
||||
| 模式 | 规则 | 详情 |
|
||||
|------|------|------|
|
||||
| 边界复制 | 在接收和返回时复制切片/map | [BOUNDARY-COPYING.md](references/BOUNDARY-COPYING.md) |
|
||||
| Defer 清理 | 在 `os.Open` 之后立即 `defer f.Close()` | 见下文 |
|
||||
| 接口检查 | `var _ I = (*T)(nil)` | 参见 go-interfaces |
|
||||
| 时间类型 | `time.Time` / `time.Duration`，绝不用原始 int | [TIME-ENUMS-TAGS.md](references/TIME-ENUMS-TAGS.md) |
|
||||
| 枚举起始值 | `iota + 1` 使零值 = 无效 | 见下文 |
|
||||
| 加密随机数 | 用 `crypto/rand` 生成密钥，绝不用 `math/rand` | 见下文 |
|
||||
| Must 函数 | 仅在初始化时使用；失败时 panic | [MUST-FUNCTIONS.md](references/MUST-FUNCTIONS.md) |
|
||||
| Panic/recover | 绝不跨包暴露 panic | [PANIC-RECOVER.md](references/PANIC-RECOVER.md) |
|
||||
| 可变全局变量 | 用依赖注入替代 | 见下文 |
|
||||
|
||||
---
|
||||
|
||||
## 验证接口合规性
|
||||
|
||||
使用编译时检查来验证接口实现。完整模式请参见 **go-interfaces**：接口满足检查。
|
||||
|
||||
```go
|
||||
var _ http.Handler = (*Handler)(nil)
|
||||
```
|
||||
|
||||
## 在边界处复制切片和 Map
|
||||
|
||||
切片和 map 包含指向底层数据的指针。在 API 边界处复制，以防止意外修改。
|
||||
|
||||
```go
|
||||
// 接收：复制传入的切片
|
||||
d.trips = make([]Trip, len(trips))
|
||||
copy(d.trips, trips)
|
||||
|
||||
// 返回：在返回之前复制 map
|
||||
result := make(map[string]int, len(s.counters))
|
||||
for k, v := range s.counters { result[k] = v }
|
||||
```
|
||||
|
||||
> 在 API 边界处复制切片或 map，或决定何时需要防御性复制、何时可以跳过时，请阅读 [references/BOUNDARY-COPYING.md](references/BOUNDARY-COPYING.md)。
|
||||
|
||||
## 使用 Defer 清理资源
|
||||
|
||||
使用 `defer` 清理资源（文件、锁）。避免在多个返回路径中遗漏清理。
|
||||
|
||||
```go
|
||||
p.Lock()
|
||||
defer p.Unlock()
|
||||
|
||||
if p.count < 10 {
|
||||
return p.count
|
||||
}
|
||||
p.count++
|
||||
return p.count
|
||||
```
|
||||
|
||||
Defer 的开销可以忽略不计。在 `os.Open` 之后立即放置 `defer f.Close()` 以提高清晰度。延迟函数的参数在 `defer` 执行时求值，而非在函数运行时。多个 defer 按 LIFO 顺序执行。
|
||||
|
||||
## 结构体字段标签
|
||||
|
||||
> **建议**：始终为需要序列化或反序列化的结构体添加显式字段标签。
|
||||
|
||||
```go
|
||||
type User struct {
|
||||
Name string `json:"name" yaml:"name"`
|
||||
Email string `json:"email" yaml:"email"`
|
||||
}
|
||||
```
|
||||
|
||||
字段标签是**序列化契约**——重命名结构体字段而不更新标签会悄然破坏线格式兼容性。对于任何跨越序列化边界的类型，应将标签视为公共 API 的一部分。
|
||||
|
||||
## 枚举从 1 开始
|
||||
|
||||
枚举从非零值开始，以区分未初始化的值和有效值。
|
||||
|
||||
```go
|
||||
const (
|
||||
Add Operation = iota + 1 // Add=1，零值 = 未初始化
|
||||
Subtract
|
||||
Multiply
|
||||
)
|
||||
```
|
||||
|
||||
**例外**：当零值是合理的默认值时（例如 `LogToStdout = iota`）。
|
||||
|
||||
## 时间、结构体标签和嵌入
|
||||
|
||||
> 在使用 `time.Time`/`time.Duration` 代替原始 int、为序列化结构体添加字段标签，或决定是否在公共结构体中嵌入类型时，请阅读 [references/TIME-ENUMS-TAGS.md](references/TIME-ENUMS-TAGS.md)。
|
||||
|
||||
## 避免可变全局变量
|
||||
|
||||
通过注入依赖代替修改包级变量。这使代码可以在不需要全局 save/restore 的情况下进行测试。
|
||||
|
||||
```go
|
||||
type signer struct {
|
||||
now func() time.Time // 注入的；测试中用固定时间替换
|
||||
}
|
||||
|
||||
func newSigner() *signer {
|
||||
return &signer{now: time.Now}
|
||||
}
|
||||
```
|
||||
|
||||
> 在决定全局变量是否合适、设计 New() + Default() 包状态模式，或用依赖注入替代可变全局变量时，请阅读 [references/GLOBAL-STATE.md](references/GLOBAL-STATE.md)。
|
||||
|
||||
## 加密随机数
|
||||
|
||||
不要使用 `math/rand` 或 `math/rand/v2` 生成密钥——这是一个**安全问题**。时间种子的生成器输出是可预测的。
|
||||
|
||||
```go
|
||||
import "crypto/rand"
|
||||
|
||||
func Key() string { return rand.Text() }
|
||||
```
|
||||
|
||||
对于文本输出，直接使用 `crypto/rand.Text`，或用 `encoding/hex` 或 `encoding/base64` 编码随机字节。
|
||||
|
||||
---
|
||||
|
||||
## Panic 与 Recover
|
||||
|
||||
仅在真正不可恢复的情况下使用 `panic`。库函数应避免 panic。
|
||||
|
||||
```go
|
||||
func safelyDo(work *Work) {
|
||||
defer func() {
|
||||
if err := recover(); err != nil {
|
||||
log.Println("work failed:", err)
|
||||
}
|
||||
}()
|
||||
do(work)
|
||||
}
|
||||
```
|
||||
|
||||
**关键规则：**
|
||||
- 绝不跨包边界暴露 panic——始终转换为 error
|
||||
- 如果库确实无法在 `init()` 中完成初始化，可以接受 panic
|
||||
- 使用 recover 隔离服务器 goroutine 处理器中的 panic
|
||||
|
||||
> 在编写 HTTP 服务器中的 panic 恢复、在解析器中使用 panic 作为内部控制流机制，或在 log.Fatal 和 panic 之间做选择时，请阅读 [references/PANIC-RECOVER.md](references/PANIC-RECOVER.md)。
|
||||
|
||||
## Must 函数
|
||||
|
||||
`Must` 函数在出错时 panic——**仅**在程序初始化阶段使用，因为失败意味着程序无法运行。
|
||||
|
||||
```go
|
||||
var validID = regexp.MustCompile(`^[a-z][a-z0-9-]{0,62}$`)
|
||||
var tmpl = template.Must(template.ParseFiles("index.html"))
|
||||
```
|
||||
|
||||
> 在编写自定义 Must 函数、决定 Must 是否适用于特定调用点，或将可能失败的初始化包装在 panic 辅助函数中时，请阅读 [references/MUST-FUNCTIONS.md](references/MUST-FUNCTIONS.md)。
|
||||
|
||||
---
|
||||
|
||||
## 相关技能
|
||||
|
||||
- **错误处理**：在选择返回错误还是 panic，或在边界处包装错误时，参见 [go-error-handling](../go-error-handling/SKILL.md)
|
||||
- **并发安全**：在使用互斥锁、原子操作或通道保护共享状态时，参见 [go-concurrency](../go-concurrency/SKILL.md)
|
||||
- **接口检查**：在添加编译时接口满足检查（`var _ I = (*T)(nil)`）时，参见 [go-interfaces](../go-interfaces/SKILL.md)
|
||||
- **数据结构复制**：在处理切片/map 内部结构或指针别名时，参见 [go-data-structures](../go-data-structures/SKILL.md)
|
||||
@@ -1,101 +0,0 @@
|
||||
# 在 API 边界处复制切片和 Map
|
||||
|
||||
> **来源**：Uber 风格指南
|
||||
|
||||
切片和 map 包含对其底层数据的引用。在 API 边界处复制它们，以防止调用者修改内部状态（反之亦然）。
|
||||
|
||||
## 接收切片和 Map
|
||||
|
||||
当函数存储调用者传入的切片或 map 时，始终进行防御性复制。调用者保留原始引用，可以在函数返回后修改它。
|
||||
|
||||
### 切片
|
||||
|
||||
**不好**
|
||||
```go
|
||||
func (d *Driver) SetTrips(trips []Trip) {
|
||||
d.trips = trips // 调用者仍然可以修改 d.trips
|
||||
}
|
||||
```
|
||||
|
||||
**好**
|
||||
```go
|
||||
func (d *Driver) SetTrips(trips []Trip) {
|
||||
d.trips = make([]Trip, len(trips))
|
||||
copy(d.trips, trips)
|
||||
}
|
||||
```
|
||||
|
||||
### Map
|
||||
|
||||
**不好**
|
||||
```go
|
||||
func (s *Server) SetConfig(cfg map[string]string) {
|
||||
s.config = cfg // 调用者仍然可以修改 s.config
|
||||
}
|
||||
```
|
||||
|
||||
**好**
|
||||
```go
|
||||
func (s *Server) SetConfig(cfg map[string]string) {
|
||||
s.config = make(map[string]string, len(cfg))
|
||||
for k, v := range cfg {
|
||||
s.config[k] = v
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 返回切片和 Map
|
||||
|
||||
返回内部切片或 map 时，返回副本以防止调用者修改你的内部状态。
|
||||
|
||||
### 返回 Map
|
||||
|
||||
**不好**
|
||||
```go
|
||||
func (s *Stats) Snapshot() map[string]int {
|
||||
s.mu.Lock()
|
||||
defer s.mu.Unlock()
|
||||
return s.counters // 暴露了内部状态！
|
||||
}
|
||||
```
|
||||
|
||||
**好**
|
||||
```go
|
||||
func (s *Stats) Snapshot() map[string]int {
|
||||
s.mu.Lock()
|
||||
defer s.mu.Unlock()
|
||||
result := make(map[string]int, len(s.counters))
|
||||
for k, v := range s.counters {
|
||||
result[k] = v
|
||||
}
|
||||
return result
|
||||
}
|
||||
```
|
||||
|
||||
### 返回切片
|
||||
|
||||
**不好**
|
||||
```go
|
||||
func (q *Queue) Items() []Item {
|
||||
return q.items // 调用者可以追加、修改或重新切片
|
||||
}
|
||||
```
|
||||
|
||||
**好**
|
||||
```go
|
||||
func (q *Queue) Items() []Item {
|
||||
result := make([]Item, len(q.items))
|
||||
copy(result, q.items)
|
||||
return result
|
||||
}
|
||||
```
|
||||
|
||||
## 何时不需要复制
|
||||
|
||||
防御性复制有开销。在以下情况下可以跳过：
|
||||
|
||||
- 数据**按约定是不可变的**，并且有清晰的文档说明
|
||||
- 切片/map 是**为调用者新创建的**（不在内部存储）
|
||||
- 性能分析表明复制在热路径中是瓶颈
|
||||
|
||||
如有疑问，就复制。与共享引用导致的 bug 相比，开销通常可以忽略不计。
|
||||
@@ -1,144 +0,0 @@
|
||||
# 全局状态模式
|
||||
|
||||
> **来源**：Google 风格指南, Effective Go
|
||||
|
||||
全局状态使程序更难以测试、推理和维护。依赖注入是首选替代方案，但某些全局状态在谨慎使用时是可以接受的。
|
||||
|
||||
## 何时可以接受全局状态
|
||||
|
||||
并非所有包级变量都有害。当全局状态是**真正进程级别的**且**不值得注入**时，它是合适的：
|
||||
|
||||
- **默认实例**——`http.DefaultClient`、`log.Default()`、`flag.CommandLine`
|
||||
- **一次编译的值**——包级别的 `regexp.MustCompile(...)`
|
||||
- **注册表**——`database/sql.Register`、`image.RegisterFormat`
|
||||
- **单例基础设施**——进程级别的指标收集器或追踪导出器
|
||||
|
||||
## 全局变量的试金石测试
|
||||
|
||||
在添加包级变量之前，请问自己：
|
||||
|
||||
1. **它是否真正是进程级别的？** 如果两个 goroutine 或测试可能需要不同的值，它不应该是全局的
|
||||
2. **它是否妨碍了测试？** 如果测试必须保存/恢复变量，或因此无法并行运行，应改为注入
|
||||
3. **它可以是常量吗？** 如果值在初始化后永远不会改变，优先使用 `const` 或未导出的只初始化一次的 `var`
|
||||
4. **它是否携带可变状态？** 可变全局变量是最危险的——仅在有完善文档、并发安全的单例情况下才可接受
|
||||
|
||||
## 包状态 API 模式：New() + Default()
|
||||
|
||||
标准库模式同时提供可定制的构造器和便捷的默认值。这使调用者可以在简单场景下使用默认值，在测试或特殊行为需求下注入自定义实例。
|
||||
|
||||
**好**
|
||||
```go
|
||||
package mylog
|
||||
|
||||
type Logger struct {
|
||||
prefix string
|
||||
out io.Writer
|
||||
}
|
||||
|
||||
func New(prefix string, out io.Writer) *Logger {
|
||||
return &Logger{prefix: prefix, out: out}
|
||||
}
|
||||
|
||||
var defaultLogger = New("", os.Stderr)
|
||||
|
||||
func Default() *Logger { return defaultLogger }
|
||||
|
||||
func (l *Logger) Info(msg string) {
|
||||
fmt.Fprintf(l.out, "%s%s\n", l.prefix, msg)
|
||||
}
|
||||
|
||||
// 包级便捷函数委托给默认实例。
|
||||
func Info(msg string) { defaultLogger.Info(msg) }
|
||||
```
|
||||
|
||||
```go
|
||||
// 调用者在简单场景下使用默认值
|
||||
mylog.Info("starting server")
|
||||
|
||||
// 测试或特殊代码创建自定义实例
|
||||
logger := mylog.New("[test] ", &buf)
|
||||
logger.Info("test message")
|
||||
```
|
||||
|
||||
此模式的标准库示例：
|
||||
- `log.New()` + `log.Default()` + `log.Println()`
|
||||
- `http.NewServeMux()` + `http.DefaultServeMux`
|
||||
- `flag.NewFlagSet()` + `flag.CommandLine`
|
||||
|
||||
## 依赖注入作为首选替代方案
|
||||
|
||||
当代码需要可配置行为时，通过构造器参数或结构体字段接受依赖，而非读取包级变量。
|
||||
|
||||
**不好**
|
||||
```go
|
||||
var db *sql.DB
|
||||
|
||||
func GetUser(id int) (*User, error) {
|
||||
return db.QueryRow("SELECT ...", id) // 依赖全局变量
|
||||
}
|
||||
```
|
||||
|
||||
**好**
|
||||
```go
|
||||
type UserStore struct {
|
||||
db *sql.DB
|
||||
}
|
||||
|
||||
func NewUserStore(db *sql.DB) *UserStore {
|
||||
return &UserStore{db: db}
|
||||
}
|
||||
|
||||
func (s *UserStore) GetUser(id int) (*User, error) {
|
||||
return s.db.QueryRow("SELECT ...", id)
|
||||
}
|
||||
```
|
||||
|
||||
注入的好处：
|
||||
- 测试可以提供 mock 或内存实现
|
||||
- 多个实例可以共存（例如，只读副本与主库）
|
||||
- 依赖在构造器签名中是显式的
|
||||
|
||||
## 注入时间
|
||||
|
||||
一个常见场景：替换 `time.Now` 以实现确定性测试。
|
||||
|
||||
**不好**
|
||||
```go
|
||||
func IsExpired(expiry time.Time) bool {
|
||||
return time.Now().After(expiry) // 不可测试
|
||||
}
|
||||
```
|
||||
|
||||
**好**
|
||||
```go
|
||||
type Checker struct {
|
||||
now func() time.Time
|
||||
}
|
||||
|
||||
func NewChecker() *Checker {
|
||||
return &Checker{now: time.Now}
|
||||
}
|
||||
|
||||
func (c *Checker) IsExpired(expiry time.Time) bool {
|
||||
return c.now().After(expiry)
|
||||
}
|
||||
```
|
||||
|
||||
测试用固定函数替换 `now`：
|
||||
|
||||
```go
|
||||
c := &Checker{now: func() time.Time {
|
||||
return time.Date(2025, 1, 1, 0, 0, 0, 0, time.UTC)
|
||||
}}
|
||||
```
|
||||
|
||||
## 总结
|
||||
|
||||
| 场景 | 方法 |
|
||||
|------|------|
|
||||
| 进程级单例（日志、指标） | 默认实例 + `New()` 构造器 |
|
||||
| 一次编译的正则或模板 | 包级 `var` 配合 `MustCompile` |
|
||||
| 注册表（数据库驱动、编解码器） | 包级 `Register()` 函数 |
|
||||
| 可配置行为 | 通过构造器进行依赖注入 |
|
||||
| 时间相关逻辑 | 注入 `func() time.Time` |
|
||||
| 测试需要变化的任何东西 | 不要使用全局状态 |
|
||||
@@ -1,92 +0,0 @@
|
||||
# Must 函数
|
||||
|
||||
> **来源**：Uber 风格指南, Go 标准库约定
|
||||
|
||||
`Must` 函数包装一个可能失败的函数，在出错时 panic。**仅**在程序初始化阶段使用，因为失败意味着程序无法运行。
|
||||
|
||||
## 标准库示例
|
||||
|
||||
```go
|
||||
// regexp.MustCompile 在模式无效时 panic
|
||||
var validID = regexp.MustCompile(`^[a-z][a-z0-9-]{0,62}$`)
|
||||
|
||||
// template.Must 在模板解析失败时 panic
|
||||
var tmpl = template.Must(template.ParseFiles("index.html"))
|
||||
```
|
||||
|
||||
这些是安全的，因为它们在包初始化时运行——如果失败，程序无法正确运行。
|
||||
|
||||
## 何时使用 Must
|
||||
|
||||
```
|
||||
这是在程序初始化期间调用的吗（包级 var、init、main 设置）？
|
||||
├─ 是 → 失败是否不可恢复（配置、正则、模板）？
|
||||
│ ├─ 是 → 使用 Must 是合适的
|
||||
│ └─ 否 → 改为返回 error
|
||||
└─ 否 → 绝不使用 Must——返回 error
|
||||
```
|
||||
|
||||
### 适当的使用场景
|
||||
|
||||
- **包级 `var`**：编译正则表达式、解析模板、加载必需的配置
|
||||
- **`init()` 或 `main()` 早期**：设置程序运行所必需的资源
|
||||
- **测试辅助函数**：测试中优先使用 `t.Fatal`，但 Must 在测试 fixture 中是可以接受的
|
||||
|
||||
### 绝不使用 Must 的场景
|
||||
|
||||
- 运行时请求处理
|
||||
- 用户提供的输入
|
||||
- 可能合理失败的网络或文件操作
|
||||
- 程序启动后调用的任何代码
|
||||
|
||||
## 编写 Must 函数
|
||||
|
||||
遵循命名约定 `MustX`，其中 `X` 是可能失败的函数名：
|
||||
|
||||
```go
|
||||
func MustParseConfig(path string) *Config {
|
||||
cfg, err := ParseConfig(path)
|
||||
if err != nil {
|
||||
panic(fmt.Sprintf("parsing config %s: %v", path, err))
|
||||
}
|
||||
return cfg
|
||||
}
|
||||
```
|
||||
|
||||
### 指南
|
||||
|
||||
- **命名**：`Must` 前缀 + 可能失败的函数名（例如 `MustParse`、`MustNew`、`MustCompile`）
|
||||
- **Panic 消息**：包含输入和错误信息以便调试
|
||||
- **文档**：始终记录函数在出错时会 panic
|
||||
|
||||
```go
|
||||
// MustParseConfig 解析路径处的配置文件。
|
||||
// 如果文件无法读取或包含无效配置，则会 panic。
|
||||
func MustParseConfig(path string) *Config { ... }
|
||||
```
|
||||
|
||||
### 泛型 Must 辅助函数
|
||||
|
||||
对于一次性使用，泛型 Must 辅助函数可以避免样板代码：
|
||||
|
||||
```go
|
||||
func Must[T any](v T, err error) T {
|
||||
if err != nil {
|
||||
panic(err)
|
||||
}
|
||||
return v
|
||||
}
|
||||
|
||||
// 在包级别使用
|
||||
var cfg = Must(ParseConfig("app.yaml"))
|
||||
```
|
||||
|
||||
## 与 Panic/Recover 的关系
|
||||
|
||||
Must 函数是对 `panic` 的受控使用。它们应该：
|
||||
|
||||
- 仅在初始化期间运行（因此不需要 recover）
|
||||
- 产生清晰、可操作的 panic 消息
|
||||
- 绝不在可以返回 error 的场景中使用
|
||||
|
||||
完整的 panic/recover 模式请参见 [PANIC-RECOVER.md](PANIC-RECOVER.md)。
|
||||
@@ -1,161 +0,0 @@
|
||||
# Panic 与 Recover 模式
|
||||
|
||||
> **来源**：Effective Go
|
||||
|
||||
## Panic 指南
|
||||
|
||||
`panic` 创建一个运行时错误来停止程序。仅在真正不可恢复的情况下使用。
|
||||
|
||||
### 何时 Panic
|
||||
|
||||
真正的库函数应**避免 panic**。如果问题可以被掩盖或绕过，让程序继续运行，而不是让整个程序崩溃。
|
||||
|
||||
```go
|
||||
// 可接受：真正不可能的情况
|
||||
func CubeRoot(x float64) float64 {
|
||||
z := x/3
|
||||
for i := 0; i < 1e6; i++ {
|
||||
prevz := z
|
||||
z -= (z*z*z-x) / (3*z*z)
|
||||
if veryClose(z, prevz) {
|
||||
return z
|
||||
}
|
||||
}
|
||||
// 百万次迭代仍未收敛；出了问题。
|
||||
panic(fmt.Sprintf("CubeRoot(%g) did not converge", x))
|
||||
}
|
||||
```
|
||||
|
||||
### 初始化中的 Panic
|
||||
|
||||
例外：如果库在 `init()` 期间确实无法完成初始化，panic 可能是合理的：
|
||||
|
||||
```go
|
||||
var user = os.Getenv("USER")
|
||||
|
||||
func init() {
|
||||
if user == "" {
|
||||
panic("no value for $USER")
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 何时 Panic 是可接受的
|
||||
|
||||
除了初始化之外，panic 在以下窄泛场景中是可接受的：
|
||||
|
||||
1. **API 误用**——类似于核心语言对越界访问的 panic。`reflect` 包使用了这种方法。
|
||||
2. **带有匹配 `recover` 的内部实现细节**在包边界处。Panic 简化了深层嵌套的控制流，而公共 API 仍然返回 error（下方的 Parse/parseInt 模式）。
|
||||
3. **`panic("unreachable")`** 在 `log.Fatal` 之后，当编译器无法检测到不可达代码时。
|
||||
|
||||
#### Parse/parseInt 模式
|
||||
|
||||
在内部使用 panic 来回退复杂的递归，但始终在包边界处转换为 error：
|
||||
|
||||
```go
|
||||
func parseInt(in string) int {
|
||||
n, err := strconv.Atoi(in)
|
||||
if err != nil {
|
||||
panic(&syntaxError{"not a valid integer"})
|
||||
}
|
||||
return n
|
||||
}
|
||||
|
||||
func Parse(in string) (_ *Node, err error) {
|
||||
defer func() {
|
||||
if p := recover(); p != nil {
|
||||
sErr, ok := p.(*syntaxError)
|
||||
if !ok {
|
||||
panic(p) // 不是我们的——重新 panic
|
||||
}
|
||||
err = fmt.Errorf("syntax error: %v", sErr.msg)
|
||||
}
|
||||
}()
|
||||
// ... 内部调用 parseInt
|
||||
}
|
||||
```
|
||||
|
||||
**关键**：类型检查 `p.(*syntaxError)` 确保只捕获*我们的* panic。意外的 panic（nil 指针等）正常传播。
|
||||
|
||||
---
|
||||
|
||||
## Recover 模式
|
||||
|
||||
`recover` 重新获得对正在 panic 的 goroutine 的控制。它只在延迟函数中有效。
|
||||
|
||||
### 基本恢复模式
|
||||
|
||||
```go
|
||||
func safelyDo(work *Work) {
|
||||
defer func() {
|
||||
if err := recover(); err != nil {
|
||||
log.Println("work failed:", err)
|
||||
}
|
||||
}()
|
||||
do(work)
|
||||
}
|
||||
```
|
||||
|
||||
### 服务器 Goroutine 保护
|
||||
|
||||
在服务器中将 panic 隔离到各个 goroutine：
|
||||
|
||||
```go
|
||||
func server(workChan <-chan *Work) {
|
||||
for work := range workChan {
|
||||
go safelyDo(work) // 每个 worker 都受保护
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
如果 `do(work)` panic，结果会被记录，goroutine 干净退出而不影响其他 goroutine。
|
||||
|
||||
### 包内部的 Panic/Recover
|
||||
|
||||
在内部使用 panic 但在 API 边界处转换为 error：
|
||||
|
||||
```go
|
||||
// Error 是一个解析错误类型
|
||||
type Error string
|
||||
func (e Error) Error() string { return string(e) }
|
||||
|
||||
// 内部：使用 Error 类型 panic
|
||||
func (regexp *Regexp) error(err string) {
|
||||
panic(Error(err))
|
||||
}
|
||||
|
||||
// 外部 API：将 panic 转换为 error 返回
|
||||
func Compile(str string) (regexp *Regexp, err error) {
|
||||
regexp = new(Regexp)
|
||||
defer func() {
|
||||
if e := recover(); e != nil {
|
||||
regexp = nil
|
||||
err = e.(Error) // 如果不是我们的 Error 类型则重新 panic
|
||||
}
|
||||
}()
|
||||
return regexp.doParse(str), nil
|
||||
}
|
||||
```
|
||||
|
||||
**要点：**
|
||||
|
||||
- 延迟函数可以修改命名返回值
|
||||
- 类型断言 `e.(Error)` 对意外错误类型重新 panic
|
||||
- 绝不向客户端暴露 panic——始终在 API 边界处转换
|
||||
|
||||
---
|
||||
|
||||
## 快速参考
|
||||
|
||||
| 模式 | 描述 |
|
||||
|------|------|
|
||||
| 基本恢复 | `defer func() { if err := recover(); err != nil { ... } }()` |
|
||||
| 服务器保护 | 将每个 goroutine 处理器包装在 safelyDo 中 |
|
||||
| 包内部 | 内部 panic，在 API 边界处 recover 并返回 error |
|
||||
| 类型安全恢复 | 使用类型断言对意外错误重新 panic |
|
||||
|
||||
## 何时使用
|
||||
|
||||
- **Panic**：仅用于真正不可恢复的情况或初始化失败
|
||||
- **Recover**：服务器处理器、包内部错误简化
|
||||
- **绝不**：跨包边界暴露 panic——始终转换为 error
|
||||
@@ -1,111 +0,0 @@
|
||||
# 时间、结构体标签和嵌入模式
|
||||
|
||||
## 使用 time.Time 和 time.Duration
|
||||
|
||||
始终使用 `time` 包。避免使用原始 `int` 表示时间值。
|
||||
|
||||
### 时间点
|
||||
|
||||
**不好**
|
||||
```go
|
||||
func isActive(now, start, stop int) bool {
|
||||
return start <= now && now < stop
|
||||
}
|
||||
```
|
||||
|
||||
**好**
|
||||
```go
|
||||
func isActive(now, start, stop time.Time) bool {
|
||||
return (start.Before(now) || start.Equal(now)) && now.Before(stop)
|
||||
}
|
||||
```
|
||||
|
||||
### 时长
|
||||
|
||||
**不好**
|
||||
```go
|
||||
func poll(delay int) {
|
||||
time.Sleep(time.Duration(delay) * time.Millisecond)
|
||||
}
|
||||
poll(10) // 秒？毫秒？
|
||||
```
|
||||
|
||||
**好**
|
||||
```go
|
||||
func poll(delay time.Duration) {
|
||||
time.Sleep(delay)
|
||||
}
|
||||
poll(10 * time.Second)
|
||||
```
|
||||
|
||||
### JSON 字段
|
||||
|
||||
当无法使用 `time.Duration` 时，在字段名中包含单位：
|
||||
|
||||
**不好**
|
||||
```go
|
||||
type Config struct {
|
||||
Interval int `json:"interval"`
|
||||
}
|
||||
```
|
||||
|
||||
**好**
|
||||
```go
|
||||
type Config struct {
|
||||
IntervalMillis int `json:"intervalMillis"`
|
||||
}
|
||||
```
|
||||
|
||||
## 避免在公共结构体中嵌入类型
|
||||
|
||||
嵌入类型会泄露实现细节并阻碍类型演进。
|
||||
|
||||
**不好**
|
||||
```go
|
||||
type ConcreteList struct {
|
||||
*AbstractList
|
||||
}
|
||||
```
|
||||
|
||||
**好**
|
||||
```go
|
||||
type ConcreteList struct {
|
||||
list *AbstractList
|
||||
}
|
||||
|
||||
func (l *ConcreteList) Add(e Entity) {
|
||||
l.list.Add(e)
|
||||
}
|
||||
|
||||
func (l *ConcreteList) Remove(e Entity) {
|
||||
l.list.Remove(e)
|
||||
}
|
||||
```
|
||||
|
||||
嵌入的问题：
|
||||
- 向嵌入接口添加方法是破坏性变更
|
||||
- 从嵌入结构体移除方法是破坏性变更
|
||||
- 替换嵌入类型是破坏性变更
|
||||
|
||||
## 在序列化结构体中使用字段标签
|
||||
|
||||
始终为 JSON、YAML 等使用显式字段标签。
|
||||
|
||||
**不好**
|
||||
```go
|
||||
type Stock struct {
|
||||
Price int
|
||||
Name string
|
||||
}
|
||||
```
|
||||
|
||||
**好**
|
||||
```go
|
||||
type Stock struct {
|
||||
Price int `json:"price"`
|
||||
Name string `json:"name"`
|
||||
// 可以安全地将 Name 重命名为 Symbol
|
||||
}
|
||||
```
|
||||
|
||||
标签使序列化契约显式化，并可以安全地进行重构。
|
||||
@@ -1,167 +0,0 @@
|
||||
---
|
||||
name: go-documentation
|
||||
description: 在编写或审查 Go 包、类型、函数或方法的文档时使用。在创建新的导出类型、函数或包时也应主动使用，即使用户没有明确询问文档问题。不涵盖未导出符号的代码注释（参见 go-style-core）。
|
||||
license: Apache-2.0
|
||||
metadata:
|
||||
sources: "Google 风格指南"
|
||||
allowed-tools: Bash(bash:*)
|
||||
---
|
||||
|
||||
# Go 文档
|
||||
|
||||
## 可用脚本
|
||||
|
||||
- **`scripts/check-docs.sh`** — 报告缺少文档注释的导出函数、类型、方法、常量和包。运行 `bash scripts/check-docs.sh --help` 查看选项。
|
||||
|
||||
> 在为新包或导出类型编写文档注释并需要所有文档约定的完整参考时，请参阅 `assets/doc-template.go`。
|
||||
|
||||
---
|
||||
|
||||
## 文档注释
|
||||
|
||||
> **规范**：所有顶层导出名称必须有文档注释。
|
||||
|
||||
### 基本规则
|
||||
|
||||
1. 以被描述对象的名称开头
|
||||
2. 冠词（"a"、"an"、"the"）可以放在名称前面
|
||||
3. 使用完整句子（首字母大写，带标点符号）
|
||||
|
||||
```go
|
||||
// A Request represents a request to run a command.
|
||||
type Request struct { ...
|
||||
|
||||
// Encode writes the JSON encoding of req to w.
|
||||
func Encode(w io.Writer, req *Request) { ...
|
||||
```
|
||||
|
||||
行为不明显的未导出类型/函数也应有文档注释。
|
||||
|
||||
> **验证**：添加文档注释后，运行 `bash scripts/check-docs.sh` 验证是否有导出符号缺少文档。修复所有缺失后再继续。
|
||||
|
||||
---
|
||||
|
||||
## 注释语句
|
||||
|
||||
> **规范**：文档注释必须是完整的句子。
|
||||
|
||||
- 首字母大写，以标点符号结尾
|
||||
- 例外：如果含义清晰，可以以小写标识符开头
|
||||
- 结构体字段的行尾注释可以是短语
|
||||
|
||||
---
|
||||
|
||||
## 注释行长度
|
||||
|
||||
> **建议**：目标约 80 列，但不设硬性限制。
|
||||
|
||||
根据标点符号换行。不要拆分长 URL。
|
||||
|
||||
---
|
||||
|
||||
## 结构体文档
|
||||
|
||||
使用段落注释对字段分组。标记可选字段及默认值：
|
||||
|
||||
```go
|
||||
type Options struct {
|
||||
// 通用设置：
|
||||
Name string
|
||||
Group *FooGroup
|
||||
|
||||
// 自定义设置：
|
||||
LargeGroupThreshold int // 可选；默认值：10
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 包注释
|
||||
|
||||
> **规范**：每个包必须有且仅有一个包注释。
|
||||
|
||||
```go
|
||||
// Package math provides basic constants and mathematical functions.
|
||||
package math
|
||||
```
|
||||
|
||||
- 对于 `main` 包，使用二进制名称：`// The seed_generator command ...`
|
||||
- 对于较长的包注释，使用 `doc.go` 文件
|
||||
|
||||
> 在编写包级文档、main 包注释、doc.go 文件或可运行示例时，请阅读 [references/EXAMPLES.md](references/EXAMPLES.md)。
|
||||
|
||||
---
|
||||
|
||||
## 文档编写要点
|
||||
|
||||
> **建议**：记录非显而易见的行为，显而易见的行为无需记录。
|
||||
|
||||
| 主题 | 何时记录... | 何时跳过... |
|
||||
|------|------------|------------|
|
||||
| 参数 | 非显而易见的行为、边界情况 | 只是重复类型签名 |
|
||||
| 上下文 | 行为与标准取消不同 | 标准 `ctx.Err()` 返回 |
|
||||
| 并发 | 线程安全性不明确（例如，看似读取但内部修改） | 只读安全、修改不安全 |
|
||||
| 清理 | 始终记录资源释放要求 | — |
|
||||
| 错误 | 哨兵值、错误类型（使用 `*PathError`） | — |
|
||||
| 命名返回值 | 多个同类型参数、面向操作命名 | 类型本身已足够清晰 |
|
||||
|
||||
关键原则：
|
||||
|
||||
- 上下文取消返回 `ctx.Err()` 是隐含的 — 不要重复说明
|
||||
- 只读操作默认线程安全；修改操作默认不安全 — 不要重复说明
|
||||
- 始终记录清理要求（例如，`Call Stop to release resources`）
|
||||
- 在错误类型文档中使用指针（`*PathError`），以确保 `errors.Is`/`errors.As` 正确使用
|
||||
- 不要仅为启用裸返回而命名返回值 — 清晰性 > 简洁性
|
||||
|
||||
> 在记录参数行为、上下文取消、并发安全性、清理要求、错误返回或函数文档注释中的命名返回参数时，请阅读 [references/CONVENTIONS.md](references/CONVENTIONS.md)。
|
||||
|
||||
---
|
||||
|
||||
## 可运行示例
|
||||
|
||||
> **建议**：在测试文件（`*_test.go`）中提供可运行示例。
|
||||
|
||||
```go
|
||||
func ExampleConfig_WriteTo() {
|
||||
cfg := &Config{Name: "example"}
|
||||
cfg.WriteTo(os.Stdout)
|
||||
// Output:
|
||||
// {"name": "example"}
|
||||
}
|
||||
```
|
||||
|
||||
示例会出现在 Godoc 中，附加到对应的文档元素上。
|
||||
|
||||
> 在编写可运行 Example 函数、选择示例命名约定（Example vs ExampleType_Method）或添加包级 doc.go 文件时，请阅读 [references/EXAMPLES.md](references/EXAMPLES.md)。
|
||||
|
||||
---
|
||||
|
||||
## Godoc 格式化
|
||||
|
||||
> 在格式化 godoc 标题、链接、列表或代码块，使用信号增强来标记弃用通知，或在本地预览文档输出时，请阅读 [references/FORMATTING.md](references/FORMATTING.md)。
|
||||
|
||||
---
|
||||
|
||||
## 快速参考
|
||||
|
||||
| 主题 | 关键规则 |
|
||||
|------|---------|
|
||||
| 文档注释 | 以名称开头，使用完整句子 |
|
||||
| 行长度 | 约 80 字符，优先考虑可读性 |
|
||||
| 包注释 | 每个包一个，放在 `package` 声明之前 |
|
||||
| 参数 | 仅记录非显而易见的行为 |
|
||||
| 上下文 | 记录与隐含行为不同的例外情况 |
|
||||
| 并发 | 记录线程安全性不明确的情况 |
|
||||
| 清理 | 始终记录资源释放要求 |
|
||||
| 错误 | 记录哨兵值和类型（注意指针） |
|
||||
| 示例 | 在测试文件中使用可运行示例 |
|
||||
| 格式化 | 空行分隔段落，缩进表示代码 |
|
||||
|
||||
---
|
||||
|
||||
## 相关技能
|
||||
|
||||
- **命名约定**：在为文档注释描述的标识符选择名称时，参见 [go-naming](../go-naming/SKILL.md)
|
||||
- **测试示例**：在编写出现在 godoc 中的可运行 `Example` 测试函数时，参见 [go-testing](../go-testing/SKILL.md)
|
||||
- **Lint 强制执行**：在使用 revive 或其他 linter 强制执行文档注释存在性时，参见 [go-linting](../go-linting/SKILL.md)
|
||||
- **风格原则**：在平衡文档详细程度与清晰简洁时，参见 [go-style-core](../go-style-core/SKILL.md)
|
||||
@@ -1,61 +0,0 @@
|
||||
// Package example demonstrates proper Go documentation conventions.
|
||||
//
|
||||
// This package shows how to write doc comments for packages, types,
|
||||
// functions, methods, and constants following Google Go Style Guide
|
||||
// conventions.
|
||||
//
|
||||
// # Getting Started
|
||||
//
|
||||
// Create a new Widget with [NewWidget]:
|
||||
//
|
||||
// w := example.NewWidget("name")
|
||||
// defer w.Close()
|
||||
package example
|
||||
|
||||
import "errors"
|
||||
|
||||
// ErrNotFound is returned when a requested item does not exist.
|
||||
var ErrNotFound = errors.New("example: not found")
|
||||
|
||||
// MaxRetries is the default number of retry attempts.
|
||||
const MaxRetries = 3
|
||||
|
||||
// Widget processes items with configurable options.
|
||||
//
|
||||
// A zero-value Widget is not valid; use [NewWidget] to create one.
|
||||
// Widget is safe for concurrent use.
|
||||
//
|
||||
// # Cleanup
|
||||
//
|
||||
// Call [Widget.Close] when done to release resources.
|
||||
type Widget struct {
|
||||
name string
|
||||
}
|
||||
|
||||
// NewWidget creates a Widget with the given name.
|
||||
//
|
||||
// Name must be non-empty; NewWidget panics otherwise.
|
||||
func NewWidget(name string) *Widget {
|
||||
if name == "" {
|
||||
panic("example: name must be non-empty")
|
||||
}
|
||||
return &Widget{name: name}
|
||||
}
|
||||
|
||||
// Process handles the given input and returns the result.
|
||||
//
|
||||
// Process returns [ErrNotFound] if the input references
|
||||
// a missing item.
|
||||
func (w *Widget) Process(input string) (string, error) {
|
||||
return input, nil
|
||||
}
|
||||
|
||||
// Close releases resources held by the Widget.
|
||||
func (w *Widget) Close() error {
|
||||
return nil
|
||||
}
|
||||
|
||||
// Deprecated: Use [NewWidget] with functional options instead.
|
||||
func NewWidgetLegacy(name string) *Widget {
|
||||
return NewWidget(name)
|
||||
}
|
||||
@@ -1,239 +0,0 @@
|
||||
# 文档约定参考
|
||||
|
||||
## 参数和配置
|
||||
|
||||
> **建议**：记录容易出错或非显而易见的参数，而非所有参数。
|
||||
|
||||
```go
|
||||
// 不好：重复了显而易见的信息
|
||||
// Sprintf formats according to a format specifier and returns the resulting string.
|
||||
//
|
||||
// format is the format, and data is the interpolation data.
|
||||
func Sprintf(format string, data ...any) string
|
||||
|
||||
// 好：记录了非显而易见的行为
|
||||
// Sprintf formats according to a format specifier and returns the resulting string.
|
||||
//
|
||||
// The provided data is used to interpolate the format string. If the data does
|
||||
// not match the expected format verbs or the amount of data does not satisfy
|
||||
// the format specification, the function will inline warnings about formatting
|
||||
// errors into the output string.
|
||||
func Sprintf(format string, data ...any) string
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 上下文
|
||||
|
||||
> **建议**：不要重复隐含的上下文行为；记录例外情况。
|
||||
|
||||
上下文取消被隐含地认为会中断函数并返回 `ctx.Err()`。不要记录这一点。
|
||||
|
||||
```go
|
||||
// 不好：重复了隐含的行为
|
||||
// Run executes the worker's run loop.
|
||||
//
|
||||
// The method will process work until the context is cancelled.
|
||||
func (Worker) Run(ctx context.Context) error
|
||||
|
||||
// 好：只记录关键信息
|
||||
// Run executes the worker's run loop.
|
||||
func (Worker) Run(ctx context.Context) error
|
||||
```
|
||||
|
||||
**当行为不同时记录：**
|
||||
|
||||
```go
|
||||
// 好：非标准的取消行为
|
||||
// Run executes the worker's run loop.
|
||||
//
|
||||
// If the context is cancelled, Run returns a nil error.
|
||||
func (Worker) Run(ctx context.Context) error
|
||||
|
||||
// 好：特殊的上下文要求
|
||||
// NewReceiver starts receiving messages sent to the specified queue.
|
||||
// The context should not have a deadline.
|
||||
func NewReceiver(ctx context.Context) *Receiver
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 并发
|
||||
|
||||
> **建议**：记录非显而易见的线程安全特性。
|
||||
|
||||
只读操作被认为是安全的；修改操作被认为是不安全的。不要重复说明这一点。
|
||||
|
||||
**何时记录：**
|
||||
|
||||
```go
|
||||
// 不明确的操作（看似只读但内部有修改）
|
||||
// Lookup returns the data associated with the key from the cache.
|
||||
//
|
||||
// This operation is not safe for concurrent use.
|
||||
func (*Cache) Lookup(key string) (data []byte, ok bool)
|
||||
|
||||
// API 提供同步机制
|
||||
// NewFortuneTellerClient returns an *rpc.Client for the FortuneTeller service.
|
||||
// It is safe for simultaneous use by multiple goroutines.
|
||||
func NewFortuneTellerClient(cc *rpc.ClientConn) *FortuneTellerClient
|
||||
|
||||
// 接口有并发要求
|
||||
// A Watcher reports the health of some entity (usually a backend service).
|
||||
//
|
||||
// Watcher methods are safe for simultaneous use by multiple goroutines.
|
||||
type Watcher interface {
|
||||
Watch(changed chan<- bool) (unwatch func())
|
||||
Health() error
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 清理
|
||||
|
||||
> **建议**：始终记录显式清理要求。
|
||||
|
||||
```go
|
||||
// 好：
|
||||
// NewTicker returns a new Ticker containing a channel that will send the
|
||||
// current time on the channel after each tick.
|
||||
//
|
||||
// Call Stop to release the Ticker's associated resources when done.
|
||||
func NewTicker(d Duration) *Ticker
|
||||
|
||||
// 好：展示如何清理
|
||||
// Get issues a GET to the specified URL.
|
||||
//
|
||||
// When err is nil, resp always contains a non-nil resp.Body.
|
||||
// Caller should close resp.Body when done reading from it.
|
||||
//
|
||||
// resp, err := http.Get("http://example.com/")
|
||||
// if err != nil {
|
||||
// // handle error
|
||||
// }
|
||||
// defer resp.Body.Close()
|
||||
// body, err := io.ReadAll(resp.Body)
|
||||
func (c *Client) Get(url string) (resp *Response, err error)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 错误
|
||||
|
||||
> **建议**：记录重要的错误哨兵值和类型。
|
||||
|
||||
```go
|
||||
// 好：记录哨兵值
|
||||
// Read reads up to len(b) bytes from the File and stores them in b.
|
||||
//
|
||||
// At end of file, Read returns 0, io.EOF.
|
||||
func (*File) Read(b []byte) (n int, err error)
|
||||
|
||||
// 好：记录错误类型（包含指针接收者）
|
||||
// Chdir changes the current working directory to the named directory.
|
||||
//
|
||||
// If there is an error, it will be of type *PathError.
|
||||
func Chdir(dir string) error
|
||||
```
|
||||
|
||||
注意使用 `*PathError`（而非 `PathError`）可以确保 `errors.Is` 和 `errors.As` 的正确使用。
|
||||
|
||||
对于包级别的错误约定，在包注释中记录。
|
||||
|
||||
---
|
||||
|
||||
## 命名返回参数
|
||||
|
||||
> **建议**：在类型本身不够清晰时用于文档说明。
|
||||
|
||||
```go
|
||||
// 好：多个同类型参数
|
||||
func (n *Node) Children() (left, right *Node, err error)
|
||||
|
||||
// 好：面向操作的名称阐明了用法
|
||||
// The caller must arrange for the returned cancel function to be called.
|
||||
func WithTimeout(parent Context, d time.Duration) (ctx Context, cancel func())
|
||||
|
||||
// 不好：类型已经很清晰，命名没有增加信息
|
||||
func (n *Node) Parent1() (node *Node)
|
||||
func (n *Node) Parent2() (node *Node, err error)
|
||||
|
||||
// 好：类型已足够
|
||||
func (n *Node) Parent1() *Node
|
||||
func (n *Node) Parent2() (*Node, error)
|
||||
```
|
||||
|
||||
不要仅为启用裸返回而命名返回值。清晰性 > 简洁性。
|
||||
|
||||
---
|
||||
|
||||
## 弃用通知
|
||||
|
||||
> **建议**：使用 `// Deprecated:` 注释标记符号为已弃用。
|
||||
|
||||
`Deprecated:` 段落必须出现在文档注释中紧接在符号之前。应说明使用什么替代。
|
||||
|
||||
**标准格式：**
|
||||
|
||||
```
|
||||
// Deprecated: Use NewThing instead.
|
||||
```
|
||||
|
||||
Godoc 会以特殊的视觉样式渲染 `Deprecated:` 注释，使其容易被发现。
|
||||
|
||||
**函数弃用：**
|
||||
|
||||
```go
|
||||
// EstimateSize returns an approximate byte count.
|
||||
//
|
||||
// Deprecated: Use [Size] instead, which returns an exact count.
|
||||
func EstimateSize(r io.Reader) (int64, error)
|
||||
```
|
||||
|
||||
**类型弃用：**
|
||||
|
||||
```go
|
||||
// LegacyClient talks to the v1 API.
|
||||
//
|
||||
// Deprecated: Use [Client] instead, which supports v2.
|
||||
type LegacyClient struct{ /* ... */ }
|
||||
```
|
||||
|
||||
**包弃用** — 在包文档注释中添加 `Deprecated:`：
|
||||
|
||||
```go
|
||||
// Package old provides the original implementation.
|
||||
//
|
||||
// Deprecated: Use package example/new instead.
|
||||
package old
|
||||
```
|
||||
|
||||
始终建议具体的替代方案，让调用者知道迁移目标。
|
||||
|
||||
---
|
||||
|
||||
## 注释语句 — 详细说明
|
||||
|
||||
> **规范**：文档注释必须是完整的句子。
|
||||
|
||||
- 首字母大写，以标点符号结尾
|
||||
- 例外：如果含义清晰，可以以小写标识符开头
|
||||
- 结构体字段的行尾注释可以是短语：
|
||||
|
||||
```go
|
||||
// 好：
|
||||
// A Server handles serving quotes from Shakespeare.
|
||||
type Server struct {
|
||||
// BaseDir points to the base directory for Shakespeare's works.
|
||||
//
|
||||
// Expected structure:
|
||||
// {BaseDir}/manifest.json
|
||||
// {BaseDir}/{name}/{name}-part{number}.txt
|
||||
BaseDir string
|
||||
|
||||
WelcomeMessage string // 用户登录时显示
|
||||
ProtocolVersion string // 与传入请求进行校验
|
||||
PageLength int // 每页行数（可选；默认值：20）
|
||||
}
|
||||
```
|
||||
@@ -1,107 +0,0 @@
|
||||
# 包注释和示例参考
|
||||
|
||||
## 包注释
|
||||
|
||||
> **规范**：每个包必须有且仅有一个包注释。
|
||||
|
||||
```go
|
||||
// 好：
|
||||
// Package math provides basic constants and mathematical functions.
|
||||
//
|
||||
// This package does not guarantee bit-identical results across architectures.
|
||||
package math
|
||||
```
|
||||
|
||||
### Main 包
|
||||
|
||||
使用二进制名称（与 BUILD 文件匹配）：
|
||||
|
||||
```go
|
||||
// 好：
|
||||
// The seed_generator command is a utility that generates a Finch seed file
|
||||
// from a set of JSON study configs.
|
||||
package main
|
||||
```
|
||||
|
||||
有效格式：`Binary seed_generator`、`Command seed_generator`、`The seed_generator command`、`Seed_generator ...`
|
||||
|
||||
### doc.go
|
||||
|
||||
- 对于较长的包注释，使用仅包含包注释和 `package` 声明的 `doc.go` 文件
|
||||
- 放在 import 之后的维护者注释不会出现在 Godoc 中
|
||||
- 保持 doc.go 文件专注于面向用户的文档
|
||||
|
||||
```go
|
||||
// Package complex provides advanced mathematical operations for
|
||||
// complex number arithmetic, including polar form conversion,
|
||||
// matrix operations, and numerical integration.
|
||||
//
|
||||
// Basic usage
|
||||
//
|
||||
// Create a complex number and perform operations:
|
||||
//
|
||||
// z := complex.New(3, 4)
|
||||
// magnitude := z.Abs() // 5.0
|
||||
// conjugate := z.Conj() // (3, -4)
|
||||
//
|
||||
// Matrix operations
|
||||
//
|
||||
// The package supports complex-valued matrices:
|
||||
//
|
||||
// m := complex.NewMatrix(2, 2)
|
||||
// m.Set(0, 0, complex.New(1, 0))
|
||||
// det := m.Det()
|
||||
package complex
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 可运行示例
|
||||
|
||||
> **建议**：提供可运行示例来展示包的用法。
|
||||
|
||||
将示例放在测试文件（`*_test.go`）中：
|
||||
|
||||
```go
|
||||
// 好：
|
||||
func ExampleConfig_WriteTo() {
|
||||
cfg := &Config{
|
||||
Name: "example",
|
||||
}
|
||||
if err := cfg.WriteTo(os.Stdout); err != nil {
|
||||
log.Exitf("Failed to write config: %s", err)
|
||||
}
|
||||
// Output:
|
||||
// {
|
||||
// "name": "example"
|
||||
// }
|
||||
}
|
||||
```
|
||||
|
||||
示例会出现在 Godoc 中，附加到对应的文档元素上。
|
||||
|
||||
### 命名约定
|
||||
|
||||
| 函数名称 | 文档对象 |
|
||||
|----------|---------|
|
||||
| `Example()` | 包级别示例 |
|
||||
| `ExampleFoo()` | 函数 `Foo` |
|
||||
| `ExampleBar_Baz()` | 方法 `Bar.Baz` |
|
||||
| `ExampleFoo_suffix()` | `Foo` 示例的命名变体 |
|
||||
|
||||
### 技巧
|
||||
|
||||
- 使用 `// Output:` 注释使示例可通过 `go test` 进行测试和验证
|
||||
- 保持示例专注于展示一个概念
|
||||
- 使用真实但精简的数据
|
||||
- 对于复杂的设置，使用 `testMain` 或辅助函数保持示例主体简洁
|
||||
- 同一符号的多个示例使用小写 `_suffix`：
|
||||
|
||||
```go
|
||||
func ExampleNewClient_withTimeout() {
|
||||
ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
|
||||
defer cancel()
|
||||
client := NewClient(ctx)
|
||||
// ...
|
||||
}
|
||||
```
|
||||
@@ -1,85 +0,0 @@
|
||||
# Godoc 格式化参考
|
||||
|
||||
## Godoc 格式化
|
||||
|
||||
> **建议**：使用 godoc 语法编写格式良好的文档。
|
||||
|
||||
**段落** - 用空行分隔：
|
||||
|
||||
```go
|
||||
// 好：
|
||||
// LoadConfig reads a configuration out of the named file.
|
||||
//
|
||||
// See some/shortlink for config file format details.
|
||||
```
|
||||
|
||||
**逐字/代码块** - 额外缩进两个空格：
|
||||
|
||||
```go
|
||||
// 好：
|
||||
// Update runs the function in an atomic transaction.
|
||||
//
|
||||
// This is typically used with an anonymous TransactionFunc:
|
||||
//
|
||||
// if err := db.Update(func(state *State) { state.Foo = bar }); err != nil {
|
||||
// //...
|
||||
// }
|
||||
```
|
||||
|
||||
**列表和表格** - 使用逐字格式：
|
||||
|
||||
```go
|
||||
// 好：
|
||||
// LoadConfig treats the following keys in special ways:
|
||||
// "import" will make this configuration inherit from the named file.
|
||||
// "env" if present will be populated with the system environment.
|
||||
```
|
||||
|
||||
**标题** - 单行，首字母大写，无标点（括号/逗号除外），后跟段落：
|
||||
|
||||
```go
|
||||
// 好：
|
||||
// Using headings
|
||||
//
|
||||
// Headings come with autogenerated anchor tags for easy linking.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 信号增强
|
||||
|
||||
> **建议**：添加注释以突出不寻常或容易被忽略的模式。
|
||||
|
||||
以下两种情况很难区分：
|
||||
|
||||
```go
|
||||
if err := doSomething(); err != nil { // 常见
|
||||
// ...
|
||||
}
|
||||
|
||||
if err := doSomething(); err == nil { // 不寻常！
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
添加注释来增强信号：
|
||||
|
||||
```go
|
||||
// 好：
|
||||
if err := doSomething(); err == nil { // 如果没有错误
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 文档预览
|
||||
|
||||
> **建议**：在代码审查之前和期间预览文档。
|
||||
|
||||
```bash
|
||||
go install golang.org/x/pkgsite/cmd/pkgsite@latest
|
||||
pkgsite
|
||||
```
|
||||
|
||||
这可以验证 godoc 格式化是否正确渲染。
|
||||
@@ -1,298 +0,0 @@
|
||||
#!/usr/bin/env bash
|
||||
set -euo pipefail
|
||||
|
||||
VERSION="1.0.0"
|
||||
SCRIPT_NAME="$(basename "$0")"
|
||||
|
||||
usage() {
|
||||
cat <<EOF
|
||||
$SCRIPT_NAME v$VERSION — Check for missing doc comments on exported Go symbols
|
||||
|
||||
USAGE
|
||||
bash $SCRIPT_NAME [options] [path]
|
||||
|
||||
DESCRIPTION
|
||||
Scans Go source files for exported functions, types, methods, constants,
|
||||
and variables that lack doc comments. Go convention requires all exported
|
||||
symbols to have a doc comment starting with the symbol name.
|
||||
|
||||
Exits 0 if all exports are documented, 1 if undocumented exports found,
|
||||
2 on error.
|
||||
|
||||
OPTIONS
|
||||
-h, --help Show this help message
|
||||
-v, --version Show version
|
||||
--json Output results as JSON
|
||||
--strict Also check unexported types/functions with 5+ lines
|
||||
--limit N Show at most N results (default: all)
|
||||
|
||||
ARGUMENTS
|
||||
path Directory or file to check (default: ./...)
|
||||
|
||||
EXAMPLES
|
||||
bash $SCRIPT_NAME
|
||||
bash $SCRIPT_NAME ./pkg/api
|
||||
bash $SCRIPT_NAME --json .
|
||||
bash $SCRIPT_NAME --strict ./internal/server
|
||||
EOF
|
||||
}
|
||||
|
||||
JSON_OUTPUT=false
|
||||
STRICT=false
|
||||
LIMIT=0
|
||||
TARGET=""
|
||||
|
||||
while [[ $# -gt 0 ]]; do
|
||||
case "$1" in
|
||||
-h|--help) usage; exit 0 ;;
|
||||
-v|--version) echo "$SCRIPT_NAME v$VERSION"; exit 0 ;;
|
||||
--json) JSON_OUTPUT=true; shift ;;
|
||||
--strict) STRICT=true; shift ;;
|
||||
--limit) LIMIT="${2:?error: --limit requires a number}"; shift 2 ;;
|
||||
-*) echo "error: unknown option: $1" >&2; usage >&2; exit 2 ;;
|
||||
*) TARGET="$1"; shift ;;
|
||||
esac
|
||||
done
|
||||
|
||||
TARGET="${TARGET:-./...}"
|
||||
|
||||
json_escape() {
|
||||
local s="$1"
|
||||
s="${s//\\/\\\\}"
|
||||
s="${s//\"/\\\"}"
|
||||
s="${s//$'\t'/\\t}"
|
||||
s="${s//$'\r'/}"
|
||||
s="${s//$'\n'/\\n}"
|
||||
printf '%s' "$s"
|
||||
}
|
||||
|
||||
find_go_files() {
|
||||
local t="$1"
|
||||
if [[ -f "$t" ]]; then
|
||||
echo "$t"
|
||||
elif [[ -d "$t" ]]; then
|
||||
find "$t" -name '*.go' ! -name '*_test.go' ! -path '*/vendor/*' ! -path '*/.git/*' 2>/dev/null
|
||||
else
|
||||
local dir="${t%%/...}"
|
||||
dir="${dir:-.}"
|
||||
if [[ -d "$dir" ]]; then
|
||||
find "$dir" -name '*.go' ! -name '*_test.go' ! -path '*/vendor/*' ! -path '*/.git/*' 2>/dev/null
|
||||
else
|
||||
echo "error: path not found: $t" >&2
|
||||
exit 2
|
||||
fi
|
||||
fi
|
||||
}
|
||||
|
||||
MISSING=()
|
||||
|
||||
add_missing() {
|
||||
local file="$1" line="$2" kind="$3" name="$4"
|
||||
MISSING+=("${file}:${line}|${kind}|${name}")
|
||||
}
|
||||
|
||||
check_file() {
|
||||
local file="$1"
|
||||
local prev_line=""
|
||||
local prev_prev_line=""
|
||||
local line_num=0
|
||||
|
||||
local in_grouped_block=false
|
||||
local grouped_kind=""
|
||||
|
||||
local re_method='^func[[:space:]]+\([^)]+\)[[:space:]]+([A-Z][a-zA-Z0-9]*)\('
|
||||
local re_func='^func[[:space:]]+([A-Z][a-zA-Z0-9]*)\('
|
||||
local re_unexported_func='^func[[:space:]]+([a-z][a-zA-Z0-9]*)\('
|
||||
local re_grouped_open='^(const|var|type)[[:space:]]*\($'
|
||||
local re_exported_type='^type[[:space:]]+([A-Z][a-zA-Z0-9]*)[[:space:]]'
|
||||
local re_unexported_type='^type[[:space:]]+([a-z][a-zA-Z0-9]*)[[:space:]]'
|
||||
local re_exported_const='^const[[:space:]]+([A-Z][a-zA-Z0-9]*)[[:space:]]'
|
||||
local re_exported_var='^var[[:space:]]+([A-Z][a-zA-Z0-9]*)[[:space:]]'
|
||||
local re_grouped_exported='^[[:space:]]+([A-Z][a-zA-Z0-9]*)'
|
||||
local re_grouped_unexported='^[[:space:]]+([a-z][a-zA-Z0-9]*)'
|
||||
|
||||
while IFS= read -r line; do
|
||||
line_num=$((line_num + 1))
|
||||
|
||||
# Check exported function/method declarations
|
||||
if [[ "$line" =~ ^func[[:space:]] ]]; then
|
||||
local name=""
|
||||
local kind=""
|
||||
# Method: func (r *Type) Name(
|
||||
if [[ "$line" =~ $re_method ]]; then
|
||||
name="${BASH_REMATCH[1]}"
|
||||
kind="method"
|
||||
# Function: func Name(
|
||||
elif [[ "$line" =~ $re_func ]]; then
|
||||
name="${BASH_REMATCH[1]}"
|
||||
kind="function"
|
||||
fi
|
||||
|
||||
if [[ -n "$name" ]]; then
|
||||
if ! is_documented "$prev_line" "$prev_prev_line"; then
|
||||
add_missing "$file" "$line_num" "$kind" "$name"
|
||||
fi
|
||||
fi
|
||||
|
||||
# Strict mode: also check unexported functions
|
||||
if $STRICT && [[ -z "$name" ]] && [[ "$line" =~ $re_unexported_func ]]; then
|
||||
name="${BASH_REMATCH[1]}"
|
||||
if ! is_documented "$prev_line" "$prev_prev_line"; then
|
||||
add_missing "$file" "$line_num" "function" "$name"
|
||||
fi
|
||||
fi
|
||||
fi
|
||||
|
||||
# Check exported type declarations
|
||||
if [[ "$line" =~ $re_exported_type ]]; then
|
||||
local name="${BASH_REMATCH[1]}"
|
||||
if ! is_documented "$prev_line" "$prev_prev_line"; then
|
||||
add_missing "$file" "$line_num" "type" "$name"
|
||||
fi
|
||||
fi
|
||||
|
||||
# Strict mode: also check unexported type declarations
|
||||
if $STRICT && [[ "$line" =~ $re_unexported_type ]]; then
|
||||
local name="${BASH_REMATCH[1]}"
|
||||
if ! is_documented "$prev_line" "$prev_prev_line"; then
|
||||
add_missing "$file" "$line_num" "type" "$name"
|
||||
fi
|
||||
fi
|
||||
|
||||
# Check exported const (single-line, not in block)
|
||||
if [[ "$line" =~ $re_exported_const ]]; then
|
||||
local name="${BASH_REMATCH[1]}"
|
||||
if ! is_documented "$prev_line" "$prev_prev_line"; then
|
||||
add_missing "$file" "$line_num" "const" "$name"
|
||||
fi
|
||||
fi
|
||||
|
||||
# Check exported var (single-line, not blank identifier)
|
||||
if [[ "$line" =~ $re_exported_var ]]; then
|
||||
local name="${BASH_REMATCH[1]}"
|
||||
if ! is_documented "$prev_line" "$prev_prev_line"; then
|
||||
add_missing "$file" "$line_num" "var" "$name"
|
||||
fi
|
||||
fi
|
||||
|
||||
# Check package comment
|
||||
if [[ "$line" =~ ^package[[:space:]]+ ]]; then
|
||||
if ! is_documented "$prev_line" "$prev_prev_line"; then
|
||||
local pkg_name
|
||||
pkg_name=$(echo "$line" | sed 's/^package[[:space:]]*//;s/[[:space:]]*$//')
|
||||
add_missing "$file" "$line_num" "package" "$pkg_name"
|
||||
fi
|
||||
fi
|
||||
|
||||
# Track grouped declaration blocks: const ( ... ), var ( ... ), type ( ... )
|
||||
if [[ "$line" =~ $re_grouped_open ]]; then
|
||||
in_grouped_block=true
|
||||
grouped_kind="${BASH_REMATCH[1]}"
|
||||
fi
|
||||
if $in_grouped_block && [[ "$line" =~ ^\)[[:space:]]*$ ]]; then
|
||||
in_grouped_block=false
|
||||
grouped_kind=""
|
||||
fi
|
||||
if $in_grouped_block && [[ -n "$grouped_kind" ]]; then
|
||||
# Check for exported names inside grouped block
|
||||
if [[ "$line" =~ $re_grouped_exported ]]; then
|
||||
local gname="${BASH_REMATCH[1]}"
|
||||
if ! is_documented "$prev_line" "$prev_prev_line"; then
|
||||
add_missing "$file" "$line_num" "$grouped_kind" "$gname"
|
||||
fi
|
||||
fi
|
||||
# Strict: also check unexported names in grouped blocks
|
||||
if $STRICT && [[ "$line" =~ $re_grouped_unexported ]]; then
|
||||
local gname="${BASH_REMATCH[1]}"
|
||||
if ! is_documented "$prev_line" "$prev_prev_line"; then
|
||||
add_missing "$file" "$line_num" "$grouped_kind" "$gname"
|
||||
fi
|
||||
fi
|
||||
fi
|
||||
|
||||
prev_prev_line="$prev_line"
|
||||
prev_line="$line"
|
||||
done < "$file"
|
||||
}
|
||||
|
||||
is_documented() {
|
||||
local prev="$1"
|
||||
local prev_prev="$2"
|
||||
# Previous line is a comment (// or end of block comment */)
|
||||
if [[ "$prev" =~ ^[[:space:]]*//.* ]] || [[ "$prev" =~ \*/[[:space:]]*$ ]]; then
|
||||
return 0
|
||||
fi
|
||||
# Previous line might be empty but line before is comment (allow one blank line)
|
||||
if [[ -z "${prev// /}" ]] && [[ "$prev_prev" =~ ^[[:space:]]*//.* ]]; then
|
||||
return 0
|
||||
fi
|
||||
return 1
|
||||
}
|
||||
|
||||
FILES=()
|
||||
while IFS= read -r f; do
|
||||
[[ -n "$f" ]] && FILES+=("$f")
|
||||
done < <(find_go_files "$TARGET")
|
||||
|
||||
if [[ ${#FILES[@]} -eq 0 ]]; then
|
||||
if $JSON_OUTPUT; then
|
||||
echo '{"missing":[],"count":0,"status":"no_go_files"}'
|
||||
else
|
||||
echo "No Go files found in: $TARGET"
|
||||
fi
|
||||
exit 0
|
||||
fi
|
||||
|
||||
for file in "${FILES[@]}"; do
|
||||
check_file "$file"
|
||||
done
|
||||
|
||||
# Truncation
|
||||
TOTAL=${#MISSING[@]}
|
||||
TRUNCATED=false
|
||||
if [[ $LIMIT -gt 0 && $TOTAL -gt $LIMIT ]]; then
|
||||
MISSING=("${MISSING[@]:0:$LIMIT}")
|
||||
TRUNCATED=true
|
||||
fi
|
||||
|
||||
if $JSON_OUTPUT; then
|
||||
echo "{"
|
||||
echo ' "missing": ['
|
||||
first=true
|
||||
for entry in "${MISSING[@]+"${MISSING[@]}"}"; do
|
||||
IFS='|' read -r location kind name <<< "$entry"
|
||||
file="${location%%:*}"
|
||||
line="${location#*:}"
|
||||
$first || echo ","
|
||||
first=false
|
||||
printf ' {"file":"%s","line":%s,"kind":"%s","name":"%s"}' \
|
||||
"$(json_escape "$file")" "$line" "$(json_escape "$kind")" "$(json_escape "$name")"
|
||||
done
|
||||
echo ""
|
||||
echo " ],"
|
||||
printf ' "total": %d,\n' "$TOTAL"
|
||||
printf ' "truncated": %s\n' "$TRUNCATED"
|
||||
echo "}"
|
||||
else
|
||||
if [[ $TOTAL -eq 0 ]]; then
|
||||
echo "All exported symbols are documented."
|
||||
exit 0
|
||||
fi
|
||||
|
||||
echo "Undocumented exported symbols:"
|
||||
echo ""
|
||||
for entry in "${MISSING[@]}"; do
|
||||
IFS='|' read -r location kind name <<< "$entry"
|
||||
printf " %s [%s] %s\n" "$location" "$kind" "$name"
|
||||
done
|
||||
if $TRUNCATED; then
|
||||
echo " ... and $((TOTAL - LIMIT)) more (use --limit to adjust)"
|
||||
fi
|
||||
echo ""
|
||||
echo "Total: $TOTAL undocumented symbol(s)"
|
||||
fi
|
||||
|
||||
if [[ $TOTAL -gt 0 ]]; then
|
||||
exit 1
|
||||
fi
|
||||
exit 0
|
||||
@@ -1,168 +0,0 @@
|
||||
---
|
||||
name: go-error-handling
|
||||
description: Use when writing Go code that returns, wraps, or handles errors — choosing between sentinel errors, custom types, and fmt.Errorf (%w vs %v), structuring error flow, or deciding whether to log or return. Also use when propagating errors across package boundaries or using errors.Is/As, even if the user doesn't ask about error strategy. Does not cover panic/recover patterns (see go-defensive).
|
||||
license: Apache-2.0
|
||||
compatibility: Requires Go 1.13+ for errors.Is/errors.As and fmt.Errorf %w wrapping. Structured logging examples use slog (Go 1.21+).
|
||||
metadata:
|
||||
sources: "Google Style Guide, Uber Style Guide"
|
||||
allowed-tools: Bash(bash:*)
|
||||
---
|
||||
|
||||
# Go 错误处理
|
||||
|
||||
## 可用脚本
|
||||
|
||||
- **`scripts/check-errors.sh`** — 检测错误处理反模式：对 `err.Error()` 进行字符串比较、没有上下文的裸 `return err`、以及日志并返回违规。运行 `bash scripts/check-errors.sh --help` 查看选项。
|
||||
|
||||
在 Go 中，[错误是值](https://go.dev/blog/errors-are-values) — 它们由代码创建，也由代码消费。
|
||||
|
||||
## 选择错误策略
|
||||
|
||||
1. 系统边界（RPC、IPC、存储）？→ 使用 `%v` 包装以避免泄露内部细节
|
||||
2. 调用者需要匹配特定条件？→ 哨兵或类型化错误，使用 `%w` 包装
|
||||
3. 调用者只需要调试上下文？→ `fmt.Errorf("...: %w", err)`
|
||||
4. 叶子函数，无需包装？→ 直接返回错误
|
||||
|
||||
**默认**：使用 `%w` 包装，并将其放在格式字符串的末尾。
|
||||
|
||||
---
|
||||
|
||||
## 核心规则
|
||||
|
||||
### 永不返回具体错误类型
|
||||
|
||||
**永不从导出函数返回具体错误类型** — 具体的 `nil` 指针可能变成非 nil 接口：
|
||||
|
||||
```go
|
||||
// 不好：具体类型可能导致微妙的 bug
|
||||
func Bad() *os.PathError { /*...*/ }
|
||||
|
||||
// 好：始终返回 error 接口
|
||||
func Good() error { /*...*/ }
|
||||
```
|
||||
|
||||
### 错误字符串
|
||||
|
||||
错误字符串**不应**大写，也**不应**以标点符号结尾。例外：导出名称、专有名词或缩写。
|
||||
|
||||
```go
|
||||
// 不好
|
||||
err := fmt.Errorf("Something bad happened.")
|
||||
|
||||
// 好
|
||||
err := fmt.Errorf("something bad happened")
|
||||
```
|
||||
|
||||
对于显示的消息（日志、测试失败、API 响应），大写是适当的。
|
||||
|
||||
### 出错时的返回值
|
||||
|
||||
当函数返回错误时，调用者必须将所有非错误返回值视为未指定，除非有明确文档说明。
|
||||
|
||||
**提示**：接受 `context.Context` 的函数通常应返回 `error`，以便调用者判断上下文是否被取消。
|
||||
|
||||
---
|
||||
|
||||
## 处理错误
|
||||
|
||||
遇到错误时，做出**深思熟虑的选择** — 不要用 `_` 丢弃：
|
||||
|
||||
1. **立即处理** — 解决错误并继续
|
||||
2. **返回给调用者** — 可选择用上下文包装
|
||||
3. **在特殊情况下** — `log.Fatal` 或 `panic`
|
||||
|
||||
有意忽略时：添加注释说明原因。
|
||||
|
||||
```go
|
||||
n, _ := b.Write(p) // 永不返回非 nil 错误
|
||||
```
|
||||
|
||||
对于相关的并发操作，使用 [`errgroup`](https://pkg.go.dev/golang.org/x/sync/errgroup)：
|
||||
|
||||
```go
|
||||
g, ctx := errgroup.WithContext(ctx)
|
||||
g.Go(func() error { return task1(ctx) })
|
||||
g.Go(func() error { return task2(ctx) })
|
||||
if err := g.Wait(); err != nil { return err }
|
||||
```
|
||||
|
||||
### 避免带内错误
|
||||
|
||||
不要返回 `-1`、`nil` 或空字符串来表示错误。使用多返回值：
|
||||
|
||||
```go
|
||||
// 不好：带内错误值
|
||||
func Lookup(key string) int // 缺失时返回 -1
|
||||
|
||||
// 好：显式的 error 或 ok 值
|
||||
func Lookup(key string) (string, bool)
|
||||
```
|
||||
|
||||
这可以防止调用者写出 `Parse(Lookup(key))` — 它会导致编译时错误，因为 `Lookup(key)` 有 2 个输出。
|
||||
|
||||
---
|
||||
|
||||
## 错误流程
|
||||
|
||||
在正常代码之前处理错误。提前返回使正常路径保持无缩进：
|
||||
|
||||
```go
|
||||
// 好：错误优先，正常代码无缩进
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
// 正常代码
|
||||
```
|
||||
|
||||
**错误只处理一次** — 记录日志或返回，不要两者都做：
|
||||
|
||||
```
|
||||
遇到错误？
|
||||
├─ 调用者可以采取行动？→ 返回（通过 %w 附带上下文）
|
||||
├─ 在调用链顶部？→ 记录日志并处理
|
||||
└─ 都不是？→ 以适当级别记录日志，继续执行
|
||||
```
|
||||
|
||||
> 在组织复杂的错误流程、决定记录日志还是返回、实现一次处理模式、或选择结构化日志级别时，请阅读 [references/ERROR-FLOW.md](references/ERROR-FLOW.md)。
|
||||
|
||||
---
|
||||
|
||||
## 错误类型
|
||||
|
||||
> **建议**：推荐的最佳实践。
|
||||
|
||||
| 调用者需要匹配？ | 消息类型 | 使用方式 |
|
||||
|-----------------|---------|---------|
|
||||
| 否 | 静态 | `errors.New("message")` |
|
||||
| 否 | 动态 | `fmt.Errorf("msg: %v", val)` |
|
||||
| 是 | 静态 | `var ErrFoo = errors.New("...")` |
|
||||
| 是 | 动态 | 自定义 `error` 类型 |
|
||||
|
||||
**默认**：使用 `fmt.Errorf("...: %w", err)` 包装。升级为哨兵以使用 `errors.Is()`，升级为自定义类型以使用 `errors.As()`。
|
||||
|
||||
> 在定义哨兵错误、创建自定义错误类型、或为包 API 选择错误策略时，请阅读 [references/ERROR-TYPES.md](references/ERROR-TYPES.md)。
|
||||
|
||||
---
|
||||
|
||||
## 错误包装
|
||||
|
||||
> **建议**：推荐的最佳实践。
|
||||
|
||||
- **使用 `%v`**：在系统边界、用于日志记录、隐藏内部细节
|
||||
- **使用 `%w`**：保留错误链以供 `errors.Is`/`errors.As` 使用
|
||||
|
||||
**关键规则**：将 `%w` 放在末尾。添加调用者没有的上下文。如果注释没有增加信息，直接返回 `err`。
|
||||
|
||||
> 在决定使用 %v 还是 %w、跨包边界包装错误、或添加上下文信息时，请阅读 [references/WRAPPING.md](references/WRAPPING.md)。
|
||||
|
||||
> **验证**：实现错误处理后，运行 `bash scripts/check-errors.sh` 检测常见的反模式。然后运行 `go vet ./...` 捕获其他问题。
|
||||
|
||||
---
|
||||
|
||||
## 相关技能
|
||||
|
||||
- **错误命名**：在命名哨兵错误（`ErrFoo`）或自定义错误类型时，参见 [go-naming](../go-naming/SKILL.md)
|
||||
- **测试错误**：在使用 `errors.Is`/`errors.As` 测试错误语义或编写错误检查辅助函数时，参见 [go-testing](../go-testing/SKILL.md)
|
||||
- **Panic 处理**：在决定 panic 还是返回错误、或编写 recover 守卫时，参见 [go-defensive](../go-defensive/SKILL.md)
|
||||
- **守卫子句**：在组织提前返回的错误流程或减少嵌套时，参见 [go-control-flow](../go-control-flow/SKILL.md)
|
||||
- **日志决策**：在选择日志级别、配置结构化日志、或决定日志消息中包含什么上下文时，参见 [go-logging](../go-logging/SKILL.md)
|
||||
@@ -1,153 +0,0 @@
|
||||
# 错误流程模式
|
||||
|
||||
错误流程、一次处理原则和日志决策的详细模式。
|
||||
|
||||
## 缩进错误流程
|
||||
|
||||
在继续正常代码之前先处理错误。这通过使读者能够快速找到正常路径来提高可读性。
|
||||
|
||||
```go
|
||||
// 好：错误处理优先，正常代码无缩进
|
||||
if err != nil {
|
||||
// 错误处理
|
||||
return // 或 continue 等
|
||||
}
|
||||
// 正常代码
|
||||
```
|
||||
|
||||
```go
|
||||
// 不好：正常代码隐藏在 else 子句中
|
||||
if err != nil {
|
||||
// 错误处理
|
||||
} else {
|
||||
// 正常代码因缩进看起来不自然
|
||||
}
|
||||
```
|
||||
|
||||
### 避免对长期使用的变量使用 if 初始化语句
|
||||
|
||||
如果变量在多行中使用，将声明移出：
|
||||
|
||||
```go
|
||||
// 好：声明与错误检查分开
|
||||
x, err := f()
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
// 大量使用 x 的代码
|
||||
// 跨越多行
|
||||
```
|
||||
|
||||
```go
|
||||
// 不好：变量作用域限制在 else 块中，难以阅读
|
||||
if x, err := f(); err != nil {
|
||||
return err
|
||||
} else {
|
||||
// 大量使用 x 的代码
|
||||
// 跨越多行
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 错误只处理一次
|
||||
|
||||
当调用者收到错误时，应该**只处理一次**。选择一种响应方式：
|
||||
|
||||
1. **返回错误**（包装或原文）让调用者处理
|
||||
2. **记录日志并优雅降级**（不返回错误）
|
||||
3. **匹配并处理**特定错误情况，返回其他错误
|
||||
|
||||
**如果返回了错误，就不要自己记录日志** — 让调用者处理。对同一错误既记录日志又返回是最常见的"一次处理"违规，导致重复噪音，因为调用栈上层的调用者也会处理该错误。
|
||||
|
||||
```go
|
||||
// 不好：既记录日志又返回 — 导致日志噪音
|
||||
u, err := getUser(id)
|
||||
if err != nil {
|
||||
log.Printf("Could not get user %q: %v", id, err)
|
||||
return err // 调用者也会记录这个！
|
||||
}
|
||||
|
||||
// 好：包装并返回 — 让调用者决定如何处理
|
||||
u, err := getUser(id)
|
||||
if err != nil {
|
||||
return fmt.Errorf("get user %q: %w", id, err)
|
||||
}
|
||||
|
||||
// 好：记录日志并优雅降级（不返回错误）
|
||||
if err := emitMetrics(); err != nil {
|
||||
// 写入指标失败不应影响应用程序
|
||||
log.Printf("Could not emit metrics: %v", err)
|
||||
}
|
||||
// 继续执行...
|
||||
|
||||
// 好：匹配特定错误，返回其他错误
|
||||
tz, err := getUserTimeZone(id)
|
||||
if err != nil {
|
||||
if errors.Is(err, ErrUserNotFound) {
|
||||
// 用户不存在，使用 UTC
|
||||
tz = time.UTC
|
||||
} else {
|
||||
return fmt.Errorf("get user %q: %w", id, err)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 记录日志 vs 返回错误
|
||||
|
||||
> 错误只处理一次 — 记录日志或返回，不要两者都做。
|
||||
|
||||
### 决策流程
|
||||
|
||||
```
|
||||
遇到错误？
|
||||
├─ 调用者可以采取行动？→ 返回错误（通过 %w 附带上下文）
|
||||
├─ 在调用链顶部？→ 记录日志并处理（返回 HTTP 状态码、退出等）
|
||||
└─ 都不是？→ 以适当级别记录日志并继续
|
||||
```
|
||||
|
||||
### 不要既记录日志又返回
|
||||
|
||||
```go
|
||||
// 不好：错误既被记录又被返回 — 在日志中出现两次
|
||||
func process(ctx context.Context, id string) error {
|
||||
result, err := fetch(ctx, id)
|
||||
if err != nil {
|
||||
log.Printf("failed to fetch %s: %v", id, err)
|
||||
return fmt.Errorf("fetching %s: %w", id, err)
|
||||
}
|
||||
return handle(result)
|
||||
}
|
||||
|
||||
// 好：带上下文返回 — 让调用者决定是否记录日志
|
||||
func process(ctx context.Context, id string) error {
|
||||
result, err := fetch(ctx, id)
|
||||
if err != nil {
|
||||
return fmt.Errorf("fetching %s: %w", id, err)
|
||||
}
|
||||
return handle(result)
|
||||
}
|
||||
```
|
||||
|
||||
### 结构化日志
|
||||
|
||||
在生产代码中，优先使用结构化日志（Go 1.21+ 的 `slog`，或 `log/slog` 兼容库）而非 `log.Printf`：
|
||||
|
||||
```go
|
||||
// 好：结构化字段可被机器解析
|
||||
slog.Error("fetch failed", "id", id, "err", err)
|
||||
|
||||
// 避免：非结构化的字符串插值
|
||||
log.Printf("fetch failed for %s: %v", id, err)
|
||||
```
|
||||
|
||||
### 日志级别
|
||||
|
||||
| 级别 | 使用场景 |
|
||||
|------|---------|
|
||||
| Error | 需要关注的可操作故障 |
|
||||
| Warn | 不需要立即处理的降级行为 |
|
||||
| Info | 关键生命周期事件（启动、关闭、配置加载） |
|
||||
| Debug | 开发期间有用的诊断细节 |
|
||||
@@ -1,151 +0,0 @@
|
||||
# 错误类型参考
|
||||
|
||||
本参考涵盖结构化错误类型、哨兵错误，以及如何为你的用例选择正确的错误类型。
|
||||
|
||||
---
|
||||
|
||||
## 错误结构
|
||||
|
||||
> 错误类型决策表在父技能中（SKILL.md § 错误类型）。
|
||||
> 本参考涵盖：扩展的代码示例、哨兵错误、使用 `errors.Is`/`errors.As` 进行错误检查，以及结构化错误类型。
|
||||
|
||||
**关键考虑因素**：
|
||||
|
||||
- 调用者是否需要使用 `errors.Is` 或 `errors.As` 来匹配错误？
|
||||
- 错误消息是静态的还是需要运行时值？
|
||||
- 导出的错误变量/类型将成为公共 API 的一部分
|
||||
|
||||
```go
|
||||
// 无需匹配，静态消息
|
||||
func Open() error {
|
||||
return errors.New("could not open")
|
||||
}
|
||||
|
||||
// 需要匹配，静态消息 - 导出哨兵
|
||||
var ErrCouldNotOpen = errors.New("could not open")
|
||||
|
||||
func Open() error {
|
||||
return ErrCouldNotOpen
|
||||
}
|
||||
|
||||
// 需要匹配，动态消息 - 使用自定义类型
|
||||
type NotFoundError struct {
|
||||
File string
|
||||
}
|
||||
|
||||
func (e *NotFoundError) Error() string {
|
||||
return fmt.Sprintf("file %q not found", e.File)
|
||||
}
|
||||
|
||||
func Open(file string) error {
|
||||
return &NotFoundError{File: file}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 哨兵错误
|
||||
|
||||
最简单的结构化错误是无参数化的全局值：
|
||||
|
||||
```go
|
||||
// 好：用于程序化检查的哨兵错误
|
||||
var (
|
||||
// ErrDuplicate 在该动物已被见过时发生。
|
||||
ErrDuplicate = errors.New("duplicate")
|
||||
|
||||
// ErrMarsupial 因为我们不支持有袋类动物。
|
||||
ErrMarsupial = errors.New("marsupials are not supported")
|
||||
)
|
||||
|
||||
func process(animal Animal) error {
|
||||
switch {
|
||||
case seen[animal]:
|
||||
return ErrDuplicate
|
||||
case marsupial(animal):
|
||||
return ErrMarsupial
|
||||
}
|
||||
seen[animal] = true
|
||||
return nil
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 检查错误
|
||||
|
||||
对于直接比较（当错误未被包装时）：
|
||||
|
||||
```go
|
||||
// 好：与哨兵直接比较
|
||||
switch err := process(an); err {
|
||||
case ErrDuplicate:
|
||||
return fmt.Errorf("feed %q: %v", an, err)
|
||||
case ErrMarsupial:
|
||||
alternate := an.BackupAnimal()
|
||||
return handlePet(alternate)
|
||||
}
|
||||
```
|
||||
|
||||
当错误可能被包装时，使用 `errors.Is`：
|
||||
|
||||
```go
|
||||
// 好：适用于被包装的错误
|
||||
switch err := process(an); {
|
||||
case errors.Is(err, ErrDuplicate):
|
||||
return fmt.Errorf("feed %q: %v", an, err)
|
||||
case errors.Is(err, ErrMarsupial):
|
||||
// 尝试恢复...
|
||||
}
|
||||
```
|
||||
|
||||
**绝不**基于字符串内容匹配错误：
|
||||
|
||||
```go
|
||||
// 不好：脆弱的字符串匹配
|
||||
if regexp.MatchString(`duplicate`, err.Error()) {...}
|
||||
if regexp.MatchString(`marsupial`, err.Error()) {...}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 结构化错误类型
|
||||
|
||||
对于需要额外程序化信息的错误，使用结构体类型：
|
||||
|
||||
```go
|
||||
// 好：具有可访问字段的结构化错误
|
||||
type PathError struct {
|
||||
Op string
|
||||
Path string
|
||||
Err error
|
||||
}
|
||||
|
||||
func (e *PathError) Error() string {
|
||||
return e.Op + " " + e.Path + ": " + e.Err.Error()
|
||||
}
|
||||
|
||||
func (e *PathError) Unwrap() error { return e.Err }
|
||||
```
|
||||
|
||||
调用者可以使用 `errors.As` 提取结构化错误：
|
||||
|
||||
```go
|
||||
var pathErr *os.PathError
|
||||
if errors.As(err, &pathErr) {
|
||||
fmt.Println("Failed path:", pathErr.Path)
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 快速参考
|
||||
|
||||
| 场景 | 错误类型 |
|
||||
|------|---------|
|
||||
| 无需匹配，静态消息 | `errors.New("message")` |
|
||||
| 无需匹配，动态消息 | `fmt.Errorf("msg: %v", val)` |
|
||||
| 需要匹配，静态消息 | `var ErrFoo = errors.New(...)` |
|
||||
| 需要匹配，动态消息 | 自定义结构体类型 |
|
||||
| 检查哨兵错误 | `errors.Is(err, ErrFoo)` |
|
||||
| 提取结构化错误 | `errors.As(err, &target)` |
|
||||
@@ -1,174 +0,0 @@
|
||||
# 错误包装参考
|
||||
|
||||
本参考涵盖使用 `%v` vs `%w` 的错误包装、放置约定、向错误添加上下文以及日志最佳实践。
|
||||
|
||||
---
|
||||
|
||||
## 包装错误：%v vs %w
|
||||
|
||||
> **建议**：推荐的最佳实践。
|
||||
|
||||
`%v` 和 `%w` 的选择会显著影响错误的传播和检查方式。
|
||||
|
||||
### 使用 %v 进行简单注释
|
||||
|
||||
当你需要以下操作时使用 `%v`：
|
||||
|
||||
- 添加上下文但不保留错误链以供程序化检查
|
||||
- 创建全新的、独立的错误（特别是在 RPC/IPC 等系统边界）
|
||||
- 向人类记录或显示错误
|
||||
|
||||
```go
|
||||
// 好：%v 在系统边界 — 隐藏内部细节
|
||||
func (s *Server) SuggestFortune(ctx context.Context, req *pb.Request) (*pb.Response, error) {
|
||||
if err != nil {
|
||||
return nil, fmt.Errorf("couldn't find fortune database: %v", err)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 使用 %w 保留错误链
|
||||
|
||||
当你需要调用者以编程方式检查底层错误时使用 `%w`：
|
||||
|
||||
```go
|
||||
// 好：%w 保留错误链以供 errors.Is/errors.As 使用
|
||||
func (s *Server) internalFunction(ctx context.Context) error {
|
||||
if err != nil {
|
||||
return fmt.Errorf("couldn't find remote file: %w", err)
|
||||
}
|
||||
}
|
||||
|
||||
// 调用者现在可以检查：
|
||||
if errors.Is(err, fs.ErrNotExist) {
|
||||
// 处理未找到的情况
|
||||
}
|
||||
```
|
||||
|
||||
### 何时使用哪种
|
||||
|
||||
**使用 %w 的场景**：
|
||||
- 在添加上下文的同时保留原始错误以供程序化检查
|
||||
- 你明确记录并测试了所暴露的底层错误
|
||||
|
||||
**使用 %v 的场景**：
|
||||
- 在系统边界（RPC、IPC、存储）转换为规范错误空间
|
||||
- 向人类记录日志或显示
|
||||
- 创建隐藏实现细节的独立错误
|
||||
|
||||
---
|
||||
|
||||
## %w 的放置位置
|
||||
|
||||
> **建议**：推荐的最佳实践。
|
||||
|
||||
将 `%w` 放在错误字符串的**末尾**，使错误文本反映错误链结构：
|
||||
|
||||
```go
|
||||
// 好：%w 在末尾 — 从最新到最旧打印
|
||||
err1 := fmt.Errorf("err1")
|
||||
err2 := fmt.Errorf("err2: %w", err1)
|
||||
err3 := fmt.Errorf("err3: %w", err2)
|
||||
fmt.Println(err3) // err3: err2: err1
|
||||
```
|
||||
|
||||
```go
|
||||
// 不好：%w 在开头 — 从最旧到最新打印（令人困惑）
|
||||
err1 := fmt.Errorf("err1")
|
||||
err2 := fmt.Errorf("%w: err2", err1)
|
||||
err3 := fmt.Errorf("%w: err3", err2)
|
||||
fmt.Println(err3) // err1: err2: err3
|
||||
```
|
||||
|
||||
```go
|
||||
// 不好：%w 在中间 — 不连贯的顺序
|
||||
err1 := fmt.Errorf("err1")
|
||||
err2 := fmt.Errorf("err2-1 %w err2-2", err1)
|
||||
err3 := fmt.Errorf("err3-1 %w err3-2", err2)
|
||||
fmt.Println(err3) // err3-1 err2-1 err1 err2-2 err3-2
|
||||
```
|
||||
|
||||
**模式**：使用 `context message: %w` 的形式
|
||||
|
||||
---
|
||||
|
||||
## 向错误添加信息
|
||||
|
||||
> **建议**：推荐的最佳实践。
|
||||
|
||||
### 添加上下文，而非冗余
|
||||
|
||||
添加你拥有但调用者/被调用者可能没有的信息。避免重复底层错误已提供的信息：
|
||||
|
||||
```go
|
||||
// 好：添加有意义的上下文
|
||||
if err := os.Open("settings.txt"); err != nil {
|
||||
return fmt.Errorf("launch codes unavailable: %v", err)
|
||||
}
|
||||
// 输出：launch codes unavailable: open settings.txt: no such file or directory
|
||||
```
|
||||
|
||||
```go
|
||||
// 不好：重复了文件名
|
||||
if err := os.Open("settings.txt"); err != nil {
|
||||
return fmt.Errorf("could not open settings.txt: %v", err)
|
||||
}
|
||||
// 输出：could not open settings.txt: open settings.txt: no such file or directory
|
||||
```
|
||||
|
||||
### 不要无目的地注释
|
||||
|
||||
如果注释仅表示失败而没有添加信息，直接返回错误：
|
||||
|
||||
```go
|
||||
// 不好：注释没有增加信息
|
||||
return fmt.Errorf("failed: %v", err)
|
||||
|
||||
// 好：直接返回错误
|
||||
return err
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 记录错误日志
|
||||
|
||||
> **建议**：推荐的最佳实践。
|
||||
|
||||
当需要记录错误时，使用 `log/slog`（Go 1.21+）配合结构化键值对和适当的日志级别：
|
||||
|
||||
- **`slog.Error`**：保留用于需要调查的可操作问题。
|
||||
- **`slog.Warn`**：用于可能需要关注但不可立即操作的问题。
|
||||
- **`slog.Debug`**：用于开发追踪 — 仅在 handler 级别设为 `LevelDebug` 时才输出。
|
||||
|
||||
```go
|
||||
// 好：使用适当级别的结构化日志
|
||||
for _, q := range queries {
|
||||
slog.Debug("handling query", "query", q)
|
||||
q.Run()
|
||||
}
|
||||
|
||||
// 好：在级别检查后保护昂贵的格式化操作
|
||||
if slog.Default().Enabled(context.Background(), slog.LevelDebug) {
|
||||
slog.Debug("query plan", "explain", q.Explain())
|
||||
}
|
||||
|
||||
// 不好：即使禁用了 debug 日志也会执行昂贵的调用
|
||||
slog.Debug("query plan", "explain", q.Explain())
|
||||
```
|
||||
|
||||
### 保护敏感信息
|
||||
|
||||
注意日志消息中的 PII（个人身份信息）。许多日志接收器不适合存放敏感用户数据。
|
||||
|
||||
---
|
||||
|
||||
## 快速参考
|
||||
|
||||
| 模式 | 指导 |
|
||||
|------|------|
|
||||
| `%v` | 在系统边界使用、用于日志记录、隐藏细节 |
|
||||
| `%w` | 保留错误链以供程序化检查 |
|
||||
| `%w` 放置 | 始终在末尾：`"context: %w"` |
|
||||
| 添加上下文 | 添加新信息，不要重复现有信息 |
|
||||
| 空注释 | 直接返回 `err` 而非 `fmt.Errorf("failed: %v", err)` |
|
||||
| 日志 | 不要既记录日志又返回；使用适当的日志级别 |
|
||||
@@ -1,266 +0,0 @@
|
||||
#!/usr/bin/env bash
|
||||
set -euo pipefail
|
||||
|
||||
VERSION="1.0.0"
|
||||
SCRIPT_NAME="$(basename "$0")"
|
||||
|
||||
usage() {
|
||||
cat <<EOF
|
||||
$SCRIPT_NAME v$VERSION — Check Go code for common error handling anti-patterns
|
||||
|
||||
USAGE
|
||||
bash $SCRIPT_NAME [options] [path]
|
||||
|
||||
DESCRIPTION
|
||||
Scans Go source files for error handling anti-patterns:
|
||||
- err.Error() used in string comparison (should use errors.Is/As)
|
||||
- Bare 'return err' without wrapping context
|
||||
- Errors that are both logged and returned (handle once)
|
||||
|
||||
Exits 0 if no issues found, 1 if anti-patterns detected, 2 on error.
|
||||
|
||||
OPTIONS
|
||||
-h, --help Show this help message
|
||||
-v, --version Show version
|
||||
--json Output results as JSON
|
||||
--no-bare-return Skip the bare 'return err' check (high false-positive rate)
|
||||
--limit N Show at most N results (default: all)
|
||||
|
||||
ARGUMENTS
|
||||
path Directory or file to check (default: current directory)
|
||||
|
||||
EXAMPLES
|
||||
bash $SCRIPT_NAME
|
||||
bash $SCRIPT_NAME ./pkg/api
|
||||
bash $SCRIPT_NAME --json .
|
||||
bash $SCRIPT_NAME --no-bare-return ./internal
|
||||
EOF
|
||||
}
|
||||
|
||||
JSON_OUTPUT=false
|
||||
CHECK_BARE_RETURN=true
|
||||
LIMIT=0
|
||||
TARGET=""
|
||||
|
||||
while [[ $# -gt 0 ]]; do
|
||||
case "$1" in
|
||||
-h|--help) usage; exit 0 ;;
|
||||
-v|--version) echo "$SCRIPT_NAME v$VERSION"; exit 0 ;;
|
||||
--json) JSON_OUTPUT=true; shift ;;
|
||||
--no-bare-return) CHECK_BARE_RETURN=false; shift ;;
|
||||
--limit) LIMIT="${2:?error: --limit requires a number}"; shift 2 ;;
|
||||
-*) echo "error: unknown option: $1" >&2; usage >&2; exit 2 ;;
|
||||
*) TARGET="$1"; shift ;;
|
||||
esac
|
||||
done
|
||||
|
||||
TARGET="${TARGET:-.}"
|
||||
|
||||
json_escape() {
|
||||
local s="$1"
|
||||
s="${s//\\/\\\\}"
|
||||
s="${s//\"/\\\"}"
|
||||
s="${s//$'\t'/\\t}"
|
||||
s="${s//$'\r'/}"
|
||||
s="${s//$'\n'/\\n}"
|
||||
printf '%s' "$s"
|
||||
}
|
||||
|
||||
find_go_files() {
|
||||
local t="$1"
|
||||
if [[ -f "$t" ]]; then
|
||||
echo "$t"
|
||||
elif [[ -d "$t" ]]; then
|
||||
find "$t" -name '*.go' ! -name '*_test.go' ! -path '*/vendor/*' ! -path '*/.git/*' 2>/dev/null
|
||||
else
|
||||
local dir="${t%%/...}"
|
||||
dir="${dir:-.}"
|
||||
if [[ -d "$dir" ]]; then
|
||||
find "$dir" -name '*.go' ! -name '*_test.go' ! -path '*/vendor/*' ! -path '*/.git/*' 2>/dev/null
|
||||
else
|
||||
echo "error: path not found: $t" >&2
|
||||
exit 2
|
||||
fi
|
||||
fi
|
||||
}
|
||||
|
||||
FINDINGS=()
|
||||
|
||||
add_finding() {
|
||||
local file="$1" line="$2" rule="$3" message="$4"
|
||||
FINDINGS+=("${file}:${line}|${rule}|${message}")
|
||||
}
|
||||
|
||||
# Rule 1: err.Error() in string comparison
|
||||
check_string_error_comparison() {
|
||||
local file="$1"
|
||||
local line_num=0
|
||||
while IFS= read -r line; do
|
||||
line_num=$((line_num + 1))
|
||||
|
||||
# Pattern: err.Error() == "..." or err.Error() != "..."
|
||||
pat='\.Error\(\)[[:space:]]*(==|!=)[[:space:]]*\"'
|
||||
if [[ "$line" =~ $pat ]]; then
|
||||
add_finding "$file" "$line_num" "string-error-compare" \
|
||||
"comparing err.Error() to string; use errors.Is() or errors.As() instead"
|
||||
fi
|
||||
|
||||
# Pattern: strings.Contains(err.Error(), "...")
|
||||
pat_contains='strings\.Contains\(.*\.Error\(\)'
|
||||
if [[ "$line" =~ $pat_contains ]]; then
|
||||
add_finding "$file" "$line_num" "string-error-compare" \
|
||||
"using strings.Contains on err.Error(); use errors.Is() or errors.As() instead"
|
||||
fi
|
||||
|
||||
# Pattern: "..." == err.Error()
|
||||
pat='\"[^\"]*\"[[:space:]]*(==|!=)[[:space:]]*[a-zA-Z_][a-zA-Z0-9_]*\.Error\(\)'
|
||||
if [[ "$line" =~ $pat ]]; then
|
||||
add_finding "$file" "$line_num" "string-error-compare" \
|
||||
"comparing string to err.Error(); use errors.Is() or errors.As() instead"
|
||||
fi
|
||||
done < "$file"
|
||||
}
|
||||
|
||||
# Rule 2: Bare return err (no wrapping)
|
||||
check_bare_return_err() {
|
||||
local file="$1"
|
||||
local line_num=0
|
||||
local in_error_block=false
|
||||
|
||||
while IFS= read -r line; do
|
||||
line_num=$((line_num + 1))
|
||||
|
||||
# Detect if err != nil { block
|
||||
pat='if[[:space:]]+(.*err[[:space:]]*(!=|==)[[:space:]]*nil|err[[:space:]]*:=)'
|
||||
if [[ "$line" =~ $pat ]]; then
|
||||
in_error_block=true
|
||||
fi
|
||||
|
||||
# Check for bare "return err" that is not wrapped
|
||||
pat='^[[:space:]]*return[[:space:]]+(.*,)?[[:space:]]*err[[:space:]]*$'
|
||||
if $in_error_block && [[ "$line" =~ $pat ]]; then
|
||||
# Exclude single-line functions and main error handlers
|
||||
# Only flag if the return is just "err" (not fmt.Errorf wrapped)
|
||||
local trimmed
|
||||
trimmed=$(echo "$line" | sed 's/^[[:space:]]*//')
|
||||
if [[ "$trimmed" == "return err" ]]; then
|
||||
add_finding "$file" "$line_num" "bare-return-err" \
|
||||
"bare 'return err' without wrapping context; consider fmt.Errorf('...: %w', err)"
|
||||
fi
|
||||
fi
|
||||
|
||||
# Reset error block tracking on closing brace at same indentation
|
||||
pat_close='^[[:space:]]*\}[[:space:]]*$'
|
||||
if $in_error_block && [[ "$line" =~ $pat_close ]]; then
|
||||
in_error_block=false
|
||||
fi
|
||||
done < "$file"
|
||||
}
|
||||
|
||||
# Rule 3: Log-and-return (handle errors once)
|
||||
check_log_and_return() {
|
||||
local file="$1"
|
||||
local line_num=0
|
||||
local prev_lines=()
|
||||
|
||||
while IFS= read -r line; do
|
||||
line_num=$((line_num + 1))
|
||||
prev_lines+=("$line")
|
||||
|
||||
# Keep a small window to detect log followed by return err
|
||||
if [[ ${#prev_lines[@]} -gt 5 ]]; then
|
||||
prev_lines=("${prev_lines[@]:1}")
|
||||
fi
|
||||
|
||||
# Check if current line is 'return ... err' and a recent line logged the error
|
||||
pat='^[[:space:]]*return[[:space:]]+(.*,)?[[:space:]]*err'
|
||||
if [[ "$line" =~ $pat ]]; then
|
||||
local window_size=${#prev_lines[@]}
|
||||
for ((i=0; i<window_size-1; i++)); do
|
||||
local prev="${prev_lines[$i]}"
|
||||
# Match log.Print/Printf/Println/Error/Errorf/Warn/Warnf with err
|
||||
pat_log1='(log\.|logger\.|slog\.)[a-zA-Z]*\(.*[^a-zA-Z]err[^a-zA-Z]'
|
||||
pat_log2='(log\.|logger\.|slog\.)[a-zA-Z]*\(err[,\)]'
|
||||
if [[ "$prev" =~ $pat_log1 ]] || \
|
||||
[[ "$prev" =~ $pat_log2 ]]; then
|
||||
local log_line=$((line_num - window_size + 1 + i))
|
||||
add_finding "$file" "$log_line" "log-and-return" \
|
||||
"error is both logged (line $log_line) and returned (line $line_num); handle errors once"
|
||||
break
|
||||
fi
|
||||
done
|
||||
fi
|
||||
done < "$file"
|
||||
}
|
||||
|
||||
FILES=()
|
||||
while IFS= read -r f; do
|
||||
[[ -n "$f" ]] && FILES+=("$f")
|
||||
done < <(find_go_files "$TARGET")
|
||||
|
||||
if [[ ${#FILES[@]} -eq 0 ]]; then
|
||||
if $JSON_OUTPUT; then
|
||||
echo '{"findings":[],"count":0,"status":"no_go_files"}'
|
||||
else
|
||||
echo "No Go files found in: $TARGET"
|
||||
fi
|
||||
exit 0
|
||||
fi
|
||||
|
||||
for file in "${FILES[@]}"; do
|
||||
check_string_error_comparison "$file"
|
||||
if $CHECK_BARE_RETURN; then
|
||||
check_bare_return_err "$file"
|
||||
fi
|
||||
check_log_and_return "$file"
|
||||
done
|
||||
|
||||
# Truncation
|
||||
TOTAL=${#FINDINGS[@]}
|
||||
TRUNCATED=false
|
||||
if [[ $LIMIT -gt 0 && $TOTAL -gt $LIMIT ]]; then
|
||||
FINDINGS=("${FINDINGS[@]:0:$LIMIT}")
|
||||
TRUNCATED=true
|
||||
fi
|
||||
|
||||
if $JSON_OUTPUT; then
|
||||
echo "{"
|
||||
echo ' "findings": ['
|
||||
first=true
|
||||
for entry in "${FINDINGS[@]+"${FINDINGS[@]}"}"; do
|
||||
IFS='|' read -r location rule message <<< "$entry"
|
||||
file="${location%%:*}"
|
||||
line="${location#*:}"
|
||||
$first || echo ","
|
||||
first=false
|
||||
printf ' {"file":"%s","line":%s,"rule":"%s","message":"%s"}' \
|
||||
"$(json_escape "$file")" "$line" "$(json_escape "$rule")" "$(json_escape "$message")"
|
||||
done
|
||||
echo ""
|
||||
echo " ],"
|
||||
printf ' "total": %d,\n' "$TOTAL"
|
||||
printf ' "truncated": %s\n' "$TRUNCATED"
|
||||
echo "}"
|
||||
else
|
||||
if [[ $TOTAL -eq 0 ]]; then
|
||||
echo "No error handling anti-patterns found."
|
||||
exit 0
|
||||
fi
|
||||
|
||||
echo "Error handling anti-patterns found:"
|
||||
echo ""
|
||||
for entry in "${FINDINGS[@]}"; do
|
||||
IFS='|' read -r location rule message <<< "$entry"
|
||||
printf " %s [%s] %s\n" "$location" "$rule" "$message"
|
||||
done
|
||||
if $TRUNCATED; then
|
||||
echo " ... and $((TOTAL - LIMIT)) more (use --limit to adjust)"
|
||||
fi
|
||||
echo ""
|
||||
echo "Total: $TOTAL finding(s)"
|
||||
fi
|
||||
|
||||
if [[ $TOTAL -gt 0 ]]; then
|
||||
exit 1
|
||||
fi
|
||||
exit 0
|
||||
@@ -1,210 +0,0 @@
|
||||
---
|
||||
name: go-functional-options
|
||||
description: Use when designing a Go constructor or factory function with optional configuration — especially with 3+ optional parameters or extensible APIs. Also use when building a New* function that takes many settings, even if they don't mention "functional options" by name. Does not cover general function design (see go-functions).
|
||||
license: Apache-2.0
|
||||
metadata:
|
||||
sources: "Uber Style Guide"
|
||||
---
|
||||
|
||||
# 函数式选项模式
|
||||
|
||||
函数式选项是一种模式，你声明一个不透明的 `Option` 类型，在内部结构体中记录信息。构造函数接受可变数量的这些选项并将其应用于配置结果。
|
||||
|
||||
## 何时使用
|
||||
|
||||
在以下情况使用函数式选项：
|
||||
|
||||
- 构造函数或公共 API 上有 **3 个以上可选参数**
|
||||
- **可扩展 API**，可能随时间增加新选项
|
||||
- **良好的调用者体验**很重要（无需传递默认值）
|
||||
|
||||
## 模式
|
||||
|
||||
### 核心组件
|
||||
|
||||
1. **未导出的 `options` 结构体** - 保存所有配置
|
||||
2. **导出的 `Option` 接口** - 带有未导出的 `apply` 方法
|
||||
3. **Option 类型** - 实现接口
|
||||
4. **`With*` 构造函数** - 创建选项
|
||||
|
||||
### Option 接口
|
||||
|
||||
```go
|
||||
type Option interface {
|
||||
apply(*options)
|
||||
}
|
||||
```
|
||||
|
||||
未导出的 `apply` 方法确保只能使用来自本包的选项。
|
||||
|
||||
## 完整实现
|
||||
|
||||
```go
|
||||
package db
|
||||
|
||||
import "go.uber.org/zap"
|
||||
|
||||
// options 保存打开连接的所有配置。
|
||||
type options struct {
|
||||
cache bool
|
||||
logger *zap.Logger
|
||||
}
|
||||
|
||||
// Option 配置我们如何打开连接。
|
||||
type Option interface {
|
||||
apply(*options)
|
||||
}
|
||||
|
||||
// cacheOption 为缓存设置实现 Option（简单类型别名）。
|
||||
type cacheOption bool
|
||||
|
||||
func (c cacheOption) apply(opts *options) {
|
||||
opts.cache = bool(c)
|
||||
}
|
||||
|
||||
// WithCache 启用或禁用缓存。
|
||||
func WithCache(c bool) Option {
|
||||
return cacheOption(c)
|
||||
}
|
||||
|
||||
// loggerOption 为日志设置实现 Option（用于指针的结构体）。
|
||||
type loggerOption struct {
|
||||
Log *zap.Logger
|
||||
}
|
||||
|
||||
func (l loggerOption) apply(opts *options) {
|
||||
opts.logger = l.Log
|
||||
}
|
||||
|
||||
// WithLogger 设置连接的日志记录器。
|
||||
func WithLogger(log *zap.Logger) Option {
|
||||
return loggerOption{Log: log}
|
||||
}
|
||||
|
||||
// Open 创建一个连接。
|
||||
func Open(addr string, opts ...Option) (*Connection, error) {
|
||||
// 从默认值开始
|
||||
options := options{
|
||||
cache: defaultCache,
|
||||
logger: zap.NewNop(),
|
||||
}
|
||||
|
||||
// 应用所有提供的选项
|
||||
for _, o := range opts {
|
||||
o.apply(&options)
|
||||
}
|
||||
|
||||
// 使用 options.cache 和 options.logger...
|
||||
return &Connection{}, nil
|
||||
}
|
||||
```
|
||||
|
||||
## 使用示例
|
||||
|
||||
### 不使用函数式选项（不好）
|
||||
|
||||
```go
|
||||
// 调用者必须始终提供所有参数，即使是默认值
|
||||
db.Open(addr, db.DefaultCache, zap.NewNop())
|
||||
db.Open(addr, db.DefaultCache, log)
|
||||
db.Open(addr, false /* cache */, zap.NewNop())
|
||||
db.Open(addr, false /* cache */, log)
|
||||
```
|
||||
|
||||
### 使用函数式选项（好）
|
||||
|
||||
```go
|
||||
// 只在需要时提供选项
|
||||
db.Open(addr)
|
||||
db.Open(addr, db.WithLogger(log))
|
||||
db.Open(addr, db.WithCache(false))
|
||||
db.Open(
|
||||
addr,
|
||||
db.WithCache(false),
|
||||
db.WithLogger(log),
|
||||
)
|
||||
```
|
||||
|
||||
## 比较：函数式选项 vs 配置结构体
|
||||
|
||||
| 方面 | 函数式选项 | 配置结构体 |
|
||||
|------|-----------|-----------|
|
||||
| **可扩展性** | 添加新的 `With*` 函数 | 添加新字段（可能破坏兼容性） |
|
||||
| **默认值** | 内置于构造函数 | 零值或单独的默认值 |
|
||||
| **调用者体验** | 只指定不同的部分 | 必须构造整个结构体 |
|
||||
| **可测试性** | 选项可比较 | 结构体比较 |
|
||||
| **复杂性** | 更多样板代码 | 更简单的设置 |
|
||||
|
||||
**优先使用配置结构体的场景**：少于 3 个选项、选项很少变化、所有选项通常一起指定、或仅用于内部 API。
|
||||
|
||||
> 在决定使用函数式选项还是配置结构体、设计具有适当默认值的配置结构体 API、或评估复杂构造函数的混合方法时，请阅读 [references/OPTIONS-VS-STRUCTS.md](references/OPTIONS-VS-STRUCTS.md)。
|
||||
|
||||
## 为什么不使用闭包？
|
||||
|
||||
另一种实现使用闭包：
|
||||
|
||||
```go
|
||||
// 闭包方法（不推荐）
|
||||
type Option func(*options)
|
||||
|
||||
func WithCache(c bool) Option {
|
||||
return func(o *options) { o.cache = c }
|
||||
}
|
||||
```
|
||||
|
||||
优先使用接口方法，因为：
|
||||
|
||||
1. **可测试性** - 选项可以在测试和 mock 中进行比较
|
||||
2. **可调试性** - 选项可以实现 `fmt.Stringer`
|
||||
3. **灵活性** - 选项可以实现额外的接口
|
||||
4. **可见性** - 选项类型在文档中可见
|
||||
|
||||
## 快速参考
|
||||
|
||||
```go
|
||||
// 1. 带有默认值的未导出 options 结构体
|
||||
type options struct {
|
||||
field1 Type1
|
||||
field2 Type2
|
||||
}
|
||||
|
||||
// 2. 导出的 Option 接口，未导出的方法
|
||||
type Option interface {
|
||||
apply(*options)
|
||||
}
|
||||
|
||||
// 3. Option 类型 + apply + With* 构造函数
|
||||
type field1Option Type1
|
||||
|
||||
func (o field1Option) apply(opts *options) { opts.field1 = Type1(o) }
|
||||
func WithField1(v Type1) Option { return field1Option(v) }
|
||||
|
||||
// 4. 构造函数在默认值之上应用选项
|
||||
func New(required string, opts ...Option) (*Thing, error) {
|
||||
o := options{field1: defaultField1, field2: defaultField2}
|
||||
for _, opt := range opts {
|
||||
opt.apply(&o)
|
||||
}
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
### 检查清单
|
||||
|
||||
- [ ] `options` 结构体未导出
|
||||
- [ ] `Option` 接口有未导出的 `apply` 方法
|
||||
- [ ] 每个选项有 `With*` 构造函数
|
||||
- [ ] 默认值在应用选项之前设置
|
||||
- [ ] 必需参数与 `...Option` 分开
|
||||
|
||||
## 相关技能
|
||||
|
||||
- **接口设计**：在设计 `Option` 接口或选择接口与闭包方法时，参见 [go-interfaces](../go-interfaces/SKILL.md)
|
||||
- **命名约定**：在命名 `With*` 构造函数、选项类型或未导出的 options 结构体时，参见 [go-naming](../go-naming/SKILL.md)
|
||||
- **函数设计**：在组织文件中的构造函数或格式化可变参数签名时，参见 [go-functions](../go-functions/SKILL.md)
|
||||
- **文档**：在记录 `Option` 类型、`With*` 函数或构造函数行为时，参见 [go-documentation](../go-documentation/SKILL.md)
|
||||
|
||||
### 外部资源
|
||||
|
||||
- [Self-referential functions and the design of options](https://commandcenter.blogspot.com/2014/01/self-referential-functions-and-design.html) - Rob Pike
|
||||
- [Functional options for friendly APIs](https://dave.cheney.net/2014/10/17/functional-options-for-friendly-apis) - Dave Cheney
|
||||
@@ -1,129 +0,0 @@
|
||||
# 函数式选项 vs 配置结构体
|
||||
|
||||
> **来源**：Google 风格指南, Uber 风格指南
|
||||
|
||||
函数式选项和配置结构体解决相同的问题 — 构造函数的可选配置 — 但它们有不同的权衡。根据 API 受众、可扩展性需求和复杂性预算来选择。
|
||||
|
||||
## 决策框架
|
||||
|
||||
```
|
||||
需要可选配置？
|
||||
├─ 内部或仅测试 API？
|
||||
│ └─ 配置结构体（更简单，更少样板代码）
|
||||
├─ 具有 3 个以上选项的公共 API？
|
||||
│ └─ 函数式选项（可扩展，向后兼容）
|
||||
├─ 选项需要校验或有相互依赖？
|
||||
│ └─ 函数式选项（在 apply 或构造函数中校验）
|
||||
├─ 所有选项通常一起指定？
|
||||
│ └─ 配置结构体（一个字面量，无需 With* 仪式）
|
||||
└─ 选项可能随时间增长？
|
||||
└─ 函数式选项（添加 With* 不会破坏调用者）
|
||||
```
|
||||
|
||||
## 配置结构体模式
|
||||
|
||||
配置结构体将可选参数分组为传递给构造函数的单个结构体。零值作为默认值，或提供 `DefaultConfig()`。
|
||||
|
||||
**好**
|
||||
```go
|
||||
type Config struct {
|
||||
Timeout time.Duration // 零 = 无超时
|
||||
MaxRetry int // 零 = 无重试
|
||||
Logger *log.Logger // nil = 丢弃
|
||||
}
|
||||
|
||||
func NewClient(addr string, cfg Config) *Client {
|
||||
if cfg.Logger == nil {
|
||||
cfg.Logger = log.New(io.Discard, "", 0)
|
||||
}
|
||||
return &Client{addr: addr, cfg: cfg}
|
||||
}
|
||||
```
|
||||
|
||||
```go
|
||||
c := NewClient("localhost:8080", Config{
|
||||
Timeout: 5 * time.Second,
|
||||
MaxRetry: 3,
|
||||
})
|
||||
```
|
||||
|
||||
**不好** — 在公共 API 中依赖未导出的配置字段：
|
||||
```go
|
||||
type config struct { // 未导出：调用者无法构造
|
||||
timeout time.Duration
|
||||
}
|
||||
|
||||
func NewClient(addr string, cfg config) *Client { ... }
|
||||
```
|
||||
|
||||
### 当零值不适用时
|
||||
|
||||
如果零是一个有效的非默认值（例如，超时为 0 表示"无超时"，但期望的默认值是 30s），使用指针字段或哨兵值：
|
||||
|
||||
```go
|
||||
type Config struct {
|
||||
Timeout *time.Duration // nil = 使用默认值（30s），零 = 无超时
|
||||
}
|
||||
```
|
||||
|
||||
## 比较
|
||||
|
||||
| 方面 | 函数式选项 | 配置结构体 |
|
||||
|------|-----------|-----------|
|
||||
| **样板代码** | 高（每个选项需要类型 + apply + With*） | 低（一个结构体） |
|
||||
| **可扩展性** | 添加 `With*` — 无破坏性变更 | 添加字段 — 无破坏性变更 |
|
||||
| **向后兼容** | 对公共 API 极好 | 好（新字段获得零值） |
|
||||
| **默认值** | 内置于构造函数 | 零值或 `DefaultConfig()` |
|
||||
| **校验** | 在 `apply` 或构造函数循环中 | 在接收到结构体后的构造函数中 |
|
||||
| **可发现性** | `With*` 函数出现在 godoc 中 | 所有字段在一个结构体中可见 |
|
||||
| **可测试性** | 比较选项或测试构造函数输出 | 比较结构体字面量 |
|
||||
| **调用者体验** | 只指定与默认值不同的部分 | 必须构造结构体字面量 |
|
||||
| **零值歧义** | 无 — 未设置的选项不应用 | 可能需要指针字段 |
|
||||
|
||||
## 何时优先使用配置结构体
|
||||
|
||||
- **内部 API** — 更少的仪式，在调用处更易读
|
||||
- **少量选项（1-3 个）** — 函数式选项的开销不值得
|
||||
- **所有选项通常一起设置** — 可变参数风格没有好处
|
||||
- **不需要校验** — 简单的字段赋值即可
|
||||
- **选项是数据而非行为** — 结构体字段自然映射
|
||||
|
||||
```go
|
||||
srv := NewServer(Config{
|
||||
Port: 8080,
|
||||
TLSCert: "/path/to/cert.pem",
|
||||
TLSKey: "/path/to/key.pem",
|
||||
})
|
||||
```
|
||||
|
||||
## 何时优先使用函数式选项
|
||||
|
||||
- **公共/库 API** — 调用者不应跟踪内部配置的演变
|
||||
- **3 个以上选项**，每个都是可选的
|
||||
- **复杂默认值** — 默认值计算依赖于其他选项
|
||||
- **按选项校验** — 在 apply 时拒绝无效值
|
||||
- **选项可能增长** — 新的 `With*` 函数是纯粹增量的
|
||||
|
||||
```go
|
||||
srv := NewServer(
|
||||
WithPort(8080),
|
||||
WithTLS("/path/to/cert.pem", "/path/to/key.pem"),
|
||||
WithLogger(logger),
|
||||
)
|
||||
```
|
||||
|
||||
## 混合方法
|
||||
|
||||
对于同时需要便利性和可扩展性的 API，接受配置结构体用于常见设置，函数式选项用于高级覆盖：
|
||||
|
||||
```go
|
||||
func NewServer(cfg Config, opts ...Option) *Server {
|
||||
s := &Server{cfg: cfg}
|
||||
for _, o := range opts {
|
||||
o.apply(&s.cfg)
|
||||
}
|
||||
return s
|
||||
}
|
||||
```
|
||||
|
||||
谨慎使用 — 它增加了复杂性。每个 API 优先使用一种方法。
|
||||
@@ -1,107 +0,0 @@
|
||||
---
|
||||
name: go-functions
|
||||
description: Use when organizing functions within a Go file, formatting function signatures, designing return values, or following Printf-style naming conventions. Also use when a user is adding or refactoring any Go function, even if they don't mention function design or signature formatting. Does not cover functional options constructors (see go-functional-options).
|
||||
license: Apache-2.0
|
||||
metadata:
|
||||
sources: "Effective Go, Google Style Guide, Uber Style Guide"
|
||||
---
|
||||
|
||||
# Go 函数设计
|
||||
|
||||
> **本技能不适用的场景**：对于函数选项构造函数（`WithTimeout`、`WithLogger`），参见 [go-functional-options](../go-functional-options/SKILL.md)。对于错误返回约定，参见 [go-error-handling](../go-error-handling/SKILL.md)。对于函数和方法的命名，参见 [go-naming](../go-naming/SKILL.md)。
|
||||
|
||||
---
|
||||
|
||||
## 函数分组与排序
|
||||
|
||||
按以下规则组织文件中的函数：
|
||||
|
||||
1. 函数按**大致调用顺序**排序
|
||||
2. 函数**按接收者分组**
|
||||
3. **导出**函数排在最前面，位于 `struct`/`const`/`var` 定义之后
|
||||
4. `NewXxx`/`newXxx` 构造函数紧跟在类型定义之后
|
||||
5. 普通工具函数排在文件末尾
|
||||
|
||||
```go
|
||||
type something struct{ ... }
|
||||
|
||||
func newSomething() *something { return &something{} }
|
||||
|
||||
func (s *something) Cost() int { return calcCost(s.weights) }
|
||||
|
||||
func (s *something) Stop() { ... }
|
||||
|
||||
func calcCost(n []int) int { ... }
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 函数签名
|
||||
|
||||
> 在格式化多行签名、包装返回值、缩短调用点或用自定义类型替换裸 bool 参数时，阅读 [references/SIGNATURES.md](references/SIGNATURES.md)。
|
||||
|
||||
尽量将签名保持在一行内。当必须换行时，将**所有参数放在各自的行上**并加尾随逗号：
|
||||
|
||||
```go
|
||||
func (r *SomeType) SomeLongFunctionName(
|
||||
foo1, foo2, foo3 string,
|
||||
foo4, foo5, foo6 int,
|
||||
) {
|
||||
foo7 := bar(foo1)
|
||||
}
|
||||
```
|
||||
|
||||
为含义不明确的参数添加 `/* name */` 注释，或者更好的做法是用自定义类型替换裸 `bool` 参数。
|
||||
|
||||
---
|
||||
|
||||
## 接口指针
|
||||
|
||||
几乎不需要指向接口的指针。将接口作为值传递——底层数据仍然可以是指针。
|
||||
|
||||
```go
|
||||
// 不好：接口指针
|
||||
func process(r *io.Reader) { ... }
|
||||
|
||||
// 好：传递接口值
|
||||
func process(r io.Reader) { ... }
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Printf 与 Stringer
|
||||
|
||||
> 在使用 %v/%s/%d 之外的 Printf 动词、实现 fmt.Stringer 或 fmt.GoStringer、编写自定义 Format() 方法或调试 String() 方法中的无限递归时，阅读 [references/PRINTF-STRINGER.md](references/PRINTF-STRINGER.md)。
|
||||
|
||||
### Printf 风格函数名
|
||||
|
||||
接受格式字符串的函数应以 `f` 结尾，以便 `go vet` 支持。在 `Printf` 调用之外使用格式字符串时，将其声明为 `const`。
|
||||
|
||||
在格式化日志或错误消息中的字符串时，优先使用 `%q` 而非手动加引号的 `%s`——它能安全地转义特殊字符并加上引号：
|
||||
|
||||
```go
|
||||
return fmt.Errorf("unknown key %q", key) // 输出：unknown key "foo\nbar"
|
||||
```
|
||||
|
||||
设计具有 3 个以上可选参数的构造函数时，参见 **go-functional-options**。
|
||||
|
||||
---
|
||||
|
||||
## 快速参考
|
||||
|
||||
| 主题 | 规则 |
|
||||
|------|------|
|
||||
| 文件排序 | 类型 -> 构造函数 -> 导出 -> 未导出 -> 工具函数 |
|
||||
| 签名换行 | 所有参数各占一行，加尾随逗号 |
|
||||
| 裸参数 | 添加 `/* name */` 注释或使用自定义类型 |
|
||||
| 接口指针 | 几乎不需要；按值传递接口 |
|
||||
| Printf 函数名 | 以 `f` 结尾以支持 `go vet` |
|
||||
|
||||
---
|
||||
|
||||
## 相关技能
|
||||
|
||||
- **错误返回**：在设计错误返回模式或在多返回值函数中包装错误时，参见 [go-error-handling](../go-error-handling/SKILL.md)
|
||||
- **命名约定**：在为函数、方法命名或选择 getter/setter 模式时，参见 [go-naming](../go-naming/SKILL.md)
|
||||
- **函数选项**：在设计具有 3 个以上可选参数的构造函数时，参见 [go-functional-options](../go-functional-options/SKILL.md)
|
||||
- **格式化原则**：在决定行长度、裸返回或签名格式时，参见 [go-style-core](../go-style-core/SKILL.md)
|
||||
@@ -1,264 +0,0 @@
|
||||
# Printf、Stringer 与自定义格式化
|
||||
|
||||
Go 的 `fmt` 打印动词、`Stringer` 和 `GoStringer` 接口、自定义 `Format()` 方法以及常见陷阱的深度参考。
|
||||
|
||||
---
|
||||
|
||||
## Printf 动词
|
||||
|
||||
### 通用动词
|
||||
|
||||
| 动词 | 用途 |
|
||||
|------|------|
|
||||
| `%v` | 默认格式（结构体字段、切片元素） |
|
||||
| `%+v` | 带字段名的结构体：`{Name:alice Age:30}` |
|
||||
| `%#v` | Go 语法表示：`main.User{Name:"alice", Age:30}` |
|
||||
| `%T` | 值的类型：`main.User` |
|
||||
| `%%` | 字面百分号 |
|
||||
|
||||
### 字符串与字节动词
|
||||
|
||||
| 动词 | 用途 |
|
||||
|------|------|
|
||||
| `%s` | 纯字符串或字节切片 |
|
||||
| `%q` | 带 Go 语法转义的引号字符串：`"hello\n"` |
|
||||
| `%x` | 十六进制编码，小写：`68656c6c6f` |
|
||||
| `%X` | 十六进制编码，大写：`68656C6C6F` |
|
||||
|
||||
### 整数动词
|
||||
|
||||
| 动词 | 用途 |
|
||||
|------|------|
|
||||
| `%d` | 十进制整数 |
|
||||
| `%b` | 二进制 |
|
||||
| `%o` | 八进制 |
|
||||
| `%O` | 带 `0o` 前缀的八进制 |
|
||||
| `%x` | 十六进制，小写 |
|
||||
| `%X` | 十六进制，大写 |
|
||||
|
||||
### 浮点数动词
|
||||
|
||||
| 动词 | 用途 |
|
||||
|------|------|
|
||||
| `%f` | 小数点，无指数：`123.456` |
|
||||
| `%e` | 科学计数法：`1.23456e+02` |
|
||||
| `%g` | 紧凑格式：大指数用 `%e`，否则用 `%f` |
|
||||
|
||||
### 宽度与精度
|
||||
|
||||
```go
|
||||
fmt.Sprintf("%10d", 42) // " 42" （宽度 10，右对齐）
|
||||
fmt.Sprintf("%-10d", 42) // "42 " （宽度 10，左对齐）
|
||||
fmt.Sprintf("%.2f", 3.14159) // "3.14" （2 位小数）
|
||||
fmt.Sprintf("%010d", 42) // "0000000042" （零填充）
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 使用 `%q` 输出字符串
|
||||
|
||||
`%q` 动词在双引号内打印字符串，使空字符串和控制字符可见：
|
||||
|
||||
```go
|
||||
fmt.Printf("value %q looks like English text", someText)
|
||||
|
||||
// 不好：手动添加引号
|
||||
fmt.Printf("value \"%s\" looks like English text", someText)
|
||||
```
|
||||
|
||||
在面向人类的输出中，如果值可能为空或包含控制字符，优先使用 `%q`。
|
||||
|
||||
---
|
||||
|
||||
## Printf 之外的格式字符串
|
||||
|
||||
在 `Printf` 风格调用之外声明格式字符串时，使用 `const`。这样 `go vet` 可以进行静态分析：
|
||||
|
||||
```go
|
||||
// 不好：变量格式字符串——go vet 无法检查
|
||||
msg := "unexpected values %v, %v\n"
|
||||
fmt.Printf(msg, 1, 2)
|
||||
|
||||
// 好：常量格式字符串——go vet 可以验证
|
||||
const msg = "unexpected values %v, %v\n"
|
||||
fmt.Printf(msg, 1, 2)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Printf 风格函数的命名
|
||||
|
||||
接受格式字符串的函数应以 `f` 结尾。这样 `go vet` 可以自动检查格式字符串：
|
||||
|
||||
```go
|
||||
func Wrapf(err error, format string, args ...any) error
|
||||
```
|
||||
|
||||
如果使用非标准名称，需要告知 `go vet`：
|
||||
|
||||
```bash
|
||||
go vet -printfuncs=wrapf,statusf
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## `fmt.Stringer` 接口
|
||||
|
||||
实现 `fmt.Stringer` 来控制类型在 `%v` 和 `%s` 下的显示方式：
|
||||
|
||||
```go
|
||||
type fmt.Stringer interface {
|
||||
String() string
|
||||
}
|
||||
```
|
||||
|
||||
```go
|
||||
type Point struct{ X, Y int }
|
||||
|
||||
func (p Point) String() string {
|
||||
return fmt.Sprintf("(%d, %d)", p.X, p.Y)
|
||||
}
|
||||
|
||||
// fmt.Println(Point{1, 2}) → "(1, 2)"
|
||||
// fmt.Sprintf("point: %v", p) → "point: (1, 2)"
|
||||
// fmt.Sprintf("point: %s", p) → "point: (1, 2)"
|
||||
```
|
||||
|
||||
### 何时实现 Stringer
|
||||
|
||||
- 类型将出现在日志消息或面向用户的输出中
|
||||
- 默认的 `%v` 输出（仅字段值）不够有意义
|
||||
- 需要一种区别于序列化的、对人类友好的表示
|
||||
|
||||
---
|
||||
|
||||
## `fmt.GoStringer` 接口
|
||||
|
||||
实现 `fmt.GoStringer` 来控制 `%#v` 输出。这对于默认 Go 语法表示具有误导性或过于冗长的类型很有用：
|
||||
|
||||
```go
|
||||
type fmt.GoStringer interface {
|
||||
GoString() string
|
||||
}
|
||||
```
|
||||
|
||||
```go
|
||||
type Color struct{ R, G, B uint8 }
|
||||
|
||||
func (c Color) GoString() string {
|
||||
return fmt.Sprintf("Color(%#02x, %#02x, %#02x)", c.R, c.G, c.B)
|
||||
}
|
||||
|
||||
// fmt.Sprintf("%#v", Color{255, 128, 0})
|
||||
// → "Color(0xff, 0x80, 0x00)" 而非 "main.Color{R:0xff, G:0x80, B:0x00}"
|
||||
```
|
||||
|
||||
`GoString()` 的输出应该是有效的 Go 语法或接近有效语法——它用于调试，而非面向用户的显示。
|
||||
|
||||
---
|
||||
|
||||
## 使用 `fmt.Formatter` 自定义格式化
|
||||
|
||||
要完全控制所有格式动词，实现 `fmt.Formatter`：
|
||||
|
||||
```go
|
||||
type fmt.Formatter interface {
|
||||
Format(f fmt.State, verb rune)
|
||||
}
|
||||
```
|
||||
|
||||
```go
|
||||
type Point struct{ X, Y int }
|
||||
|
||||
func (p Point) Format(f fmt.State, verb rune) {
|
||||
switch verb {
|
||||
case 'v':
|
||||
if f.Flag('#') {
|
||||
// %#v——Go 语法表示
|
||||
fmt.Fprintf(f, "Point{X: %d, Y: %d}", p.X, p.Y)
|
||||
return
|
||||
}
|
||||
if f.Flag('+') {
|
||||
// %+v——带字段名的详细格式
|
||||
fmt.Fprintf(f, "X:%d Y:%d", p.X, p.Y)
|
||||
return
|
||||
}
|
||||
// %v——默认
|
||||
fmt.Fprintf(f, "(%d, %d)", p.X, p.Y)
|
||||
case 's':
|
||||
fmt.Fprintf(f, "(%d, %d)", p.X, p.Y)
|
||||
case 'q':
|
||||
fmt.Fprintf(f, "%q", p.String())
|
||||
default:
|
||||
fmt.Fprintf(f, "%%!%c(Point=%d,%d)", verb, p.X, p.Y)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### `fmt.State` 方法
|
||||
|
||||
| 方法 | 返回值 |
|
||||
|------|--------|
|
||||
| `Flag(c int) bool` | 标志（`+`、`-`、`#`、`0`、` `）是否设置 |
|
||||
| `Width() (int, bool)` | 宽度值以及是否指定了宽度 |
|
||||
| `Precision() (int, bool)` | 精度值以及是否指定了精度 |
|
||||
| `Write(b []byte) (int, error)` | 写入输出字节 |
|
||||
|
||||
仅在 `String()` 不够用时才实现 `fmt.Formatter`——很少需要这样做。常见原因：需要为 `%v`、`%+v`、`%#v` 提供不同输出，或者需要遵循宽度/精度标志。
|
||||
|
||||
---
|
||||
|
||||
## 无限递归陷阱
|
||||
|
||||
**在 `String()` 方法内部对接收者使用 `%s` 或 `%v` 调用 `fmt.Sprintf` 会导致无限递归：**
|
||||
|
||||
```go
|
||||
type MyString string
|
||||
|
||||
// BUG：无限递归——Sprintf 调用 String()，String() 又调用 Sprintf...
|
||||
func (m MyString) String() string {
|
||||
return fmt.Sprintf("MyString: %s", m) // 崩溃：栈溢出
|
||||
}
|
||||
```
|
||||
|
||||
修复方法——将接收者转换为其底层类型以打破方法集：
|
||||
|
||||
```go
|
||||
func (m MyString) String() string {
|
||||
return fmt.Sprintf("MyString: %s", string(m)) // 安全：string 没有 String()
|
||||
}
|
||||
```
|
||||
|
||||
此陷阱还适用于：
|
||||
- 底层类型为 string、[]byte 或另一个 Stringer 的类型
|
||||
- 任何使用 `%s` 或 `%v` 格式化 `self` 的 `String()` 方法
|
||||
- 使用 `%#v` 格式化 `self` 的 `GoString()` 方法
|
||||
|
||||
```go
|
||||
type IPAddr [4]byte
|
||||
|
||||
// BUG：%v 调用 String()，无限递归
|
||||
func (ip IPAddr) String() string {
|
||||
return fmt.Sprintf("%v.%v.%v.%v", ip[0], ip[1], ip[2], ip[3])
|
||||
// 这里安全——ip[0] 是 byte（uint8），没有 String() 方法。
|
||||
// 但如果 ip 是一个包装了 Stringer 的命名类型，就会递归。
|
||||
}
|
||||
```
|
||||
|
||||
**经验法则**：在 `String()` 内部，永远不要将接收者（或重新转换为自身类型的接收者）传递给 `%s` 或 `%v` 动词。先转换为底层原始类型。
|
||||
|
||||
---
|
||||
|
||||
## 快速参考
|
||||
|
||||
| 主题 | 规则 |
|
||||
|------|------|
|
||||
| `%q` | 用于人类可读的字符串输出 |
|
||||
| `%+v` | 带字段名的结构体 |
|
||||
| `%#v` | Go 语法表示；通过 `GoStringer` 自定义 |
|
||||
| 格式字符串存储 | 在 Printf 调用之外声明为 `const` |
|
||||
| Printf 函数名 | 以 `f` 结尾以支持 `go vet` |
|
||||
| `Stringer` | 实现 `String() string` 用于 `%v`/`%s` 输出 |
|
||||
| `GoStringer` | 实现 `GoString() string` 用于 `%#v` 输出 |
|
||||
| `Formatter` | 实现 `Format(fmt.State, rune)` 以完全控制动词 |
|
||||
| 递归陷阱 | 永远不要在 `String()` 内部使用 `Sprintf("%s", receiver)`；转换为底层类型 |
|
||||
@@ -1,168 +0,0 @@
|
||||
# 函数签名
|
||||
|
||||
格式化 Go 函数签名、避免裸参数以及保持调用点可读性的详细规则。
|
||||
|
||||
---
|
||||
|
||||
## 单行 vs 多行
|
||||
|
||||
当签名能轻松放在一行时保持单行。当必须换行时，将**所有参数放在各自的行上**并加尾随逗号：
|
||||
|
||||
**不好**——部分换行使对齐变得脆弱：
|
||||
|
||||
```go
|
||||
func (r *SomeType) SomeLongFunctionName(foo1, foo2, foo3 string,
|
||||
foo4, foo5, foo6 int) {
|
||||
foo7 := bar(foo1)
|
||||
}
|
||||
```
|
||||
|
||||
**好**——完全换行，尾随逗号：
|
||||
|
||||
```go
|
||||
func (r *SomeType) SomeLongFunctionName(
|
||||
foo1, foo2, foo3 string,
|
||||
foo4, foo5, foo6 int,
|
||||
) {
|
||||
foo7 := bar(foo1)
|
||||
}
|
||||
```
|
||||
|
||||
### 返回值
|
||||
|
||||
当返回值也需要换行时，遵循相同的模式：
|
||||
|
||||
```go
|
||||
func (r *SomeType) LongName(
|
||||
foo1, foo2, foo3 string,
|
||||
foo4, foo5, foo6 int,
|
||||
) (
|
||||
*Result,
|
||||
error,
|
||||
) {
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
对于更简单的情况，命名返回值可以与参数右括号在同一行：
|
||||
|
||||
```go
|
||||
func (r *SomeType) LongName(
|
||||
foo1, foo2, foo3 string,
|
||||
) (result *Result, err error) {
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 缩短调用点
|
||||
|
||||
提取局部变量，而不是将函数调用拆分到多行：
|
||||
|
||||
```go
|
||||
// 不好：过长的内联调用
|
||||
result := foo.Call(
|
||||
somePackage.ComplexFunction(arg1, arg2),
|
||||
anotherPackage.Transform(data),
|
||||
defaultOptions,
|
||||
)
|
||||
|
||||
// 好：提取局部变量以提高清晰度
|
||||
transformed := anotherPackage.Transform(data)
|
||||
computed := somePackage.ComplexFunction(arg1, arg2)
|
||||
result := foo.Call(computed, transformed, defaultOptions)
|
||||
```
|
||||
|
||||
这提高了可读性，并使中间值可用于调试。
|
||||
|
||||
---
|
||||
|
||||
## 避免裸参数
|
||||
|
||||
函数调用中的裸参数会降低可读性。为含义不明确的参数添加 C 风格注释：
|
||||
|
||||
```go
|
||||
// 不好：这些布尔值是什么意思？
|
||||
printInfo("foo", true, true)
|
||||
|
||||
// 好：内联注释说明了意图
|
||||
printInfo("foo", true /* isLocal */, true /* done */)
|
||||
```
|
||||
|
||||
更好的做法是用自定义类型替换裸 `bool` 参数：
|
||||
|
||||
```go
|
||||
type Region int
|
||||
|
||||
const (
|
||||
UnknownRegion Region = iota
|
||||
Local
|
||||
)
|
||||
|
||||
type Status int
|
||||
|
||||
const (
|
||||
Pending Status = iota
|
||||
Done
|
||||
)
|
||||
|
||||
func printInfo(name string, region Region, status Status)
|
||||
```
|
||||
|
||||
### 何时使用每种方法
|
||||
|
||||
| 方法 | 时机 |
|
||||
|------|------|
|
||||
| C 风格注释 | 快速修复；调用点少；无法修改的第三方 API |
|
||||
| 自定义类型 | 多个调用点；公开 API；多个 bool/int 参数 |
|
||||
| 函数选项 | 3 个以上可选参数；参见 [go-functional-options](../../go-functional-options/SKILL.md) |
|
||||
|
||||
---
|
||||
|
||||
## 分组相关参数
|
||||
|
||||
当函数接受多个相同类型的参数时，将它们分组：
|
||||
|
||||
```go
|
||||
// 可接受：将同类型参数分组
|
||||
func Copy(dst, src string) error
|
||||
|
||||
// 可接受：尽管类型相同，但含义不同时分开声明
|
||||
func Move(source string, destination string) error
|
||||
```
|
||||
|
||||
当参数名称能清楚表明角色时使用分组；当不能清楚表明时使用分开声明。
|
||||
|
||||
---
|
||||
|
||||
## 方法接收者的位置
|
||||
|
||||
接收者放在函数名之前，格式类似于参数：
|
||||
|
||||
```go
|
||||
// 短接收者——放在同一行
|
||||
func (s *Server) Start(ctx context.Context) error { ... }
|
||||
|
||||
// 长接收者类型——如果整行过长则考虑换行
|
||||
func (h *ComplicatedHandler) ServeHTTP(
|
||||
w http.ResponseWriter,
|
||||
r *http.Request,
|
||||
) { ... }
|
||||
```
|
||||
|
||||
参见 [go-naming](../../go-naming/SKILL.md) 了解接收者命名约定（简短的一到两个字母缩写）。
|
||||
|
||||
---
|
||||
|
||||
## 快速参考
|
||||
|
||||
| 主题 | 规则 |
|
||||
|------|------|
|
||||
| 单行 | 能放下时保持一行 |
|
||||
| 多行 | 所有参数各占一行，尾随逗号 |
|
||||
| 返回值换行 | 与参数相同的模式 |
|
||||
| 调用点 | 提取局部变量而不是拆分调用 |
|
||||
| 裸 bool | 添加 `/* name */` 注释或使用自定义类型 |
|
||||
| 分组参数 | 当名称能清楚表明角色时将同类型分组 |
|
||||
| 接收者 | 在函数名之前；简短缩写 |
|
||||
@@ -1,173 +0,0 @@
|
||||
---
|
||||
name: go-generics
|
||||
description: Use when deciding whether to use Go generics, writing generic functions or types, choosing constraints, or picking between type aliases and type definitions. Also use when a user is writing a utility function that could work with multiple types, even if they don't mention generics explicitly. Does not cover interface design without generics (see go-interfaces).
|
||||
license: Apache-2.0
|
||||
compatibility: Requires Go 1.18+ (generics were introduced in Go 1.18)
|
||||
metadata:
|
||||
sources: "Google Style Guide"
|
||||
---
|
||||
|
||||
# Go 泛型与类型参数
|
||||
|
||||
---
|
||||
|
||||
## 何时使用泛型
|
||||
|
||||
从具体类型开始。只在出现第二种类型时才进行泛化。
|
||||
|
||||
### 优先使用泛型的场景
|
||||
|
||||
- 多种类型共享相同的逻辑（排序、过滤、map/reduce）
|
||||
- 否则需要依赖 `any` 和大量的类型切换
|
||||
- 正在构建可复用的数据结构（并发安全的集合、有序映射）
|
||||
|
||||
### 避免使用泛型的场景
|
||||
|
||||
- 实践中只有一种类型被实例化
|
||||
- 接口已经能清晰地表达共享行为
|
||||
- 泛型代码比特定类型的替代方案更难阅读
|
||||
|
||||
> "写代码，不要设计类型。"—— Robert Griesemer 和 Ian Lance Taylor
|
||||
|
||||
### 决策流程
|
||||
|
||||
```
|
||||
多种类型是否共享相同的逻辑？
|
||||
├─ 否 → 使用具体类型
|
||||
├─ 是 → 它们是否共享一个有用的接口？
|
||||
│ ├─ 是 → 使用接口
|
||||
│ └─ 否 → 使用泛型
|
||||
```
|
||||
|
||||
**不好：**
|
||||
|
||||
```go
|
||||
// 过早使用泛型：只会被 int 调用
|
||||
func Sum[T constraints.Integer | constraints.Float](vals []T) T {
|
||||
var total T
|
||||
for _, v := range vals {
|
||||
total += v
|
||||
}
|
||||
return total
|
||||
}
|
||||
```
|
||||
|
||||
**好：**
|
||||
|
||||
```go
|
||||
func SumInts(vals []int) int {
|
||||
var total int
|
||||
for _, v := range vals {
|
||||
total += v
|
||||
}
|
||||
return total
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 类型参数命名
|
||||
|
||||
| 名称 | 典型用途 |
|
||||
|------|----------|
|
||||
| `T` | 通用类型参数 |
|
||||
| `K` | 映射键类型 |
|
||||
| `V` | 映射值类型 |
|
||||
| `E` | 元素/项目类型 |
|
||||
|
||||
对于复杂约束，可以使用简短的描述性名称：
|
||||
|
||||
```go
|
||||
func Marshal[Opts encoding.MarshalOptions](v any, opts Opts) ([]byte, error)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 类型别名 vs 类型定义
|
||||
|
||||
类型别名（`type Old = new.Name`）很少使用——仅用于包迁移或渐进式 API 重构。
|
||||
|
||||
---
|
||||
|
||||
## 约束组合
|
||||
|
||||
使用 `~`（底层类型）和 `|`（联合）组合约束：
|
||||
|
||||
```go
|
||||
type Numeric interface {
|
||||
~int | ~int8 | ~int16 | ~int32 | ~int64 |
|
||||
~float32 | ~float64
|
||||
}
|
||||
|
||||
func Sum[T Numeric](vals []T) T {
|
||||
var total T
|
||||
for _, v := range vals {
|
||||
total += v
|
||||
}
|
||||
return total
|
||||
}
|
||||
```
|
||||
|
||||
使用 `constraints` 包或 `cmp` 包（Go 1.21+）中的标准约束如 `cmp.Ordered`，而不是自己编写。
|
||||
|
||||
> 在编写自定义类型约束、使用 ~ 和 | 组合约束或调试类型推断问题时，阅读 [references/CONSTRAINTS.md](references/CONSTRAINTS.md)。
|
||||
|
||||
---
|
||||
|
||||
## 常见陷阱
|
||||
|
||||
### 不要包装标准库类型
|
||||
|
||||
```go
|
||||
// 不好：泛型包装器增加了复杂度但没有价值
|
||||
type Set[T comparable] struct {
|
||||
m map[T]struct{}
|
||||
}
|
||||
|
||||
// 更好：当用法简单时直接使用 map[T]struct{}
|
||||
seen := map[string]struct{}{}
|
||||
```
|
||||
|
||||
泛型在消除**多个调用点**之间的重复时才能证明其复杂度的合理性。单次使用的泛型只是多余的间接层。
|
||||
|
||||
### 不要为接口满足而使用泛型
|
||||
|
||||
```go
|
||||
// 不好：T 仅用于满足接口——直接使用接口即可
|
||||
func Process[T io.Reader](r T) error { ... }
|
||||
|
||||
// 好：直接接受接口
|
||||
func Process(r io.Reader) error { ... }
|
||||
```
|
||||
|
||||
### 避免过度约束
|
||||
|
||||
```go
|
||||
// 不好：约束比需要的更严格
|
||||
func Contains[T interface{ ~int | ~string }](slice []T, target T) bool { ... }
|
||||
|
||||
// 好：comparable 就足够了
|
||||
func Contains[T comparable](slice []T, target T) bool { ... }
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 快速参考
|
||||
|
||||
| 主题 | 指导 |
|
||||
|------|------|
|
||||
| 何时使用泛型 | 仅在多种类型共享相同逻辑且接口不够用时 |
|
||||
| 起点 | 先写具体代码；之后再泛化 |
|
||||
| 命名 | 单个大写字母（`T`、`K`、`V`、`E`） |
|
||||
| 类型别名 | 相同类型，替代名称；仅用于迁移 |
|
||||
| 约束组合 | 使用 `~` 表示底层类型，`|` 表示联合；优先使用 `cmp.Ordered` 而非自定义 |
|
||||
| 常见陷阱 | 不要对单次使用的代码或接口已足够时使用泛型 |
|
||||
|
||||
---
|
||||
|
||||
## 相关技能
|
||||
|
||||
- **接口 vs 泛型**：在决定接口是否已经能表达共享行为而无需泛型时，参见 [go-interfaces](../go-interfaces/SKILL.md)
|
||||
- **类型声明**：在定义新类型、类型别名或在类型定义和别名之间选择时，参见 [go-declarations](../go-declarations/SKILL.md)
|
||||
- **文档化泛型 API**：在为泛型函数编写文档注释和可运行示例时，参见 [go-documentation](../go-documentation/SKILL.md)
|
||||
- **命名类型参数**：在为类型参数或约束接口选择名称时，参见 [go-naming](../go-naming/SKILL.md)
|
||||
@@ -1,169 +0,0 @@
|
||||
# Go 泛型中的类型约束
|
||||
|
||||
> **来源**：Google Go 风格指南、Go 语言规范
|
||||
|
||||
约束定义了类型参数支持的操作。选择满足函数需求的最窄约束——不要更多。
|
||||
|
||||
---
|
||||
|
||||
## 内置约束
|
||||
|
||||
> **规范**：在自行编写约束之前，优先使用标准约束。
|
||||
|
||||
| 约束 | 含义 |
|
||||
|------|------|
|
||||
| `any` | `interface{}` 的别名；对类型没有要求 |
|
||||
| `comparable` | 支持 `==` 和 `!=`；映射键所必需 |
|
||||
| `cmp.Ordered` | 支持 `<`、`<=`、`>=`、`>`（Go 1.21+，替代 `constraints.Ordered`） |
|
||||
|
||||
在新代码中优先使用 `cmp.Ordered`（来自 `cmp` 包），而不是已弃用的 `golang.org/x/exp/constraints.Ordered`。
|
||||
|
||||
---
|
||||
|
||||
## `~` 运算符（底层类型）
|
||||
|
||||
> **建议**：当你想接受基于原始类型构建的命名类型时使用 `~`。
|
||||
|
||||
`~T` 语法匹配任何**底层类型**为 `T` 的类型。没有 `~` 时，只有精确的类型匹配。
|
||||
|
||||
```go
|
||||
type Celsius float64
|
||||
|
||||
type ExactFloat interface{ float64 } // 拒绝 Celsius
|
||||
type AnyFloat64 interface{ ~float64 } // 接受 Celsius
|
||||
```
|
||||
|
||||
当调用者可能基于基础类型定义命名类型时使用 `~`。仅在需要限制为精确的内置类型时才省略 `~`。
|
||||
|
||||
---
|
||||
|
||||
## 组合与编写约束
|
||||
|
||||
> **建议**：仅在没有标准约束适用时才定义自定义约束。
|
||||
|
||||
使用 `|` 组合类型并嵌入约束来组合它们：
|
||||
|
||||
```go
|
||||
type Numeric interface {
|
||||
~int | ~int8 | ~int16 | ~int32 | ~int64 |
|
||||
~float32 | ~float64
|
||||
}
|
||||
|
||||
type Addable interface {
|
||||
Numeric | ~string // 数字和字符串拼接
|
||||
}
|
||||
```
|
||||
|
||||
约束可以同时要求方法和类型元素：
|
||||
|
||||
```go
|
||||
type Stringer interface {
|
||||
comparable
|
||||
String() string
|
||||
}
|
||||
```
|
||||
|
||||
满足 `Stringer` 的类型必须是可比较的 **并且** 具有 `String()` 方法。
|
||||
|
||||
---
|
||||
|
||||
## 避免过度约束
|
||||
|
||||
> **规范**：使用支持所执行操作的最小约束。
|
||||
|
||||
**不好**
|
||||
```go
|
||||
// 只使用了 == 但限制为 int 和 string
|
||||
func Contains[T interface{ ~int | ~string }](s []T, v T) bool { ... }
|
||||
```
|
||||
|
||||
**好**
|
||||
```go
|
||||
// comparable 是 == 的最小约束
|
||||
func Contains[T comparable](s []T, v T) bool { ... }
|
||||
```
|
||||
|
||||
过度约束限制了复用，并迫使调用者绕过实现中根本不需要的限制。
|
||||
|
||||
## 类型推断
|
||||
|
||||
> **建议**：当类型明确时让编译器推断类型参数。
|
||||
|
||||
编译器从函数参数推断类型参数：
|
||||
|
||||
```go
|
||||
result := slices.Contains[string](names, "alice") // 显式——不必要
|
||||
result := slices.Contains(names, "alice") // 推断——推荐
|
||||
```
|
||||
|
||||
仅在以下情况下才显式提供类型参数：没有可用于推断的函数参数、推断的类型不正确（例如无类型常量提升为错误的类型），或者将类型显式展示出来有助于可读性。
|
||||
|
||||
---
|
||||
|
||||
## 常见陷阱
|
||||
|
||||
### 接口已足够时不要使用泛型
|
||||
|
||||
> **规范**：来自 Google 风格指南——当类型共享一个有用的统一接口时，优先使用接口。
|
||||
|
||||
**不好**
|
||||
```go
|
||||
// T 仅用于满足 io.Reader——直接使用接口即可
|
||||
func Process[T io.Reader](r T) error { ... }
|
||||
```
|
||||
|
||||
**好**
|
||||
```go
|
||||
func Process(r io.Reader) error { ... }
|
||||
```
|
||||
|
||||
如果约束是单个已有接口，直接接受该接口。
|
||||
|
||||
### 不要泛型地包装标准库类型
|
||||
|
||||
> **建议**：单次使用的泛型只是多余的间接层。
|
||||
|
||||
**不好**
|
||||
```go
|
||||
type Set[T comparable] struct{ m map[T]struct{} } // 永远只是 Set[string]
|
||||
```
|
||||
|
||||
**好**
|
||||
```go
|
||||
seen := map[string]struct{}{} // 对于单次实例化直接使用 map
|
||||
```
|
||||
|
||||
泛型在消除**多个调用点**之间的重复时才能证明其复杂度的合理性。如果只使用一种类型，从具体类型开始。
|
||||
|
||||
### 方法集与类型约束
|
||||
|
||||
你只能调用约束允许的操作：
|
||||
|
||||
**不好**
|
||||
```go
|
||||
func Stringify[T any](v T) string {
|
||||
return v.String() // 编译错误：any 没有 String()
|
||||
}
|
||||
```
|
||||
|
||||
**好**
|
||||
```go
|
||||
func Stringify[T fmt.Stringer](v T) string {
|
||||
return v.String()
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 快速参考
|
||||
|
||||
| 主题 | 指导 |
|
||||
|------|------|
|
||||
| 默认约束 | `any`——不需要对 T 进行任何操作时使用 |
|
||||
| 相等性检查 | `comparable`——`==`、`!=` 和映射键所必需 |
|
||||
| 排序 | `cmp.Ordered`（Go 1.21+）用于 `<`、`>` 比较 |
|
||||
| 命名类型 | 使用 `~T` 接受底层类型为 T 的类型 |
|
||||
| 联合类型 | 使用 `\|` 组合——例如 `~int \| ~float64` |
|
||||
| 自定义约束 | 定义为包含类型元素和/或方法的接口 |
|
||||
| 类型推断 | 当编译器可以推断时省略类型参数 |
|
||||
| 最小约束 | 使用函数实际需要的最窄约束 |
|
||||
@@ -1,151 +0,0 @@
|
||||
---
|
||||
name: go-interfaces
|
||||
description: Use when defining or implementing Go interfaces, designing abstractions, creating mockable boundaries for testing, or composing types through embedding. Also use when deciding whether to accept an interface or return a concrete type, or using type assertions or type switches, even if the user doesn't explicitly mention interfaces. Does not cover generics-based polymorphism (see go-generics).
|
||||
license: Apache-2.0
|
||||
metadata:
|
||||
sources: "Effective Go, Google Style Guide, Uber Style Guide"
|
||||
allowed-tools: Bash(bash:*)
|
||||
---
|
||||
|
||||
# Go 接口与组合
|
||||
|
||||
## 可用脚本
|
||||
|
||||
- **`scripts/check-interface-compliance.sh`**——查找缺少编译时合规性检查（`var _ I = (*T)(nil)`）的导出接口。运行 `bash scripts/check-interface-compliance.sh --help` 查看选项。
|
||||
|
||||
---
|
||||
|
||||
## 接受接口，返回具体类型
|
||||
|
||||
接口属于**消费**值的包，而不是**实现**值的包。从构造函数返回具体类型（通常是指针或结构体），这样可以在不重构的情况下添加新方法。
|
||||
|
||||
```go
|
||||
// 好：消费者定义自己需要的接口
|
||||
package consumer
|
||||
|
||||
type Thinger interface { Thing() bool }
|
||||
|
||||
func Foo(t Thinger) string { ... }
|
||||
```
|
||||
|
||||
```go
|
||||
// 好：生产者返回具体类型
|
||||
package producer
|
||||
|
||||
type Thinger struct{ ... }
|
||||
func (t Thinger) Thing() bool { ... }
|
||||
func NewThinger() Thinger { return Thinger{ ... } }
|
||||
```
|
||||
|
||||
```go
|
||||
// 不好：生产者定义并返回自己的接口
|
||||
package producer
|
||||
|
||||
type Thinger interface { Thing() bool }
|
||||
type defaultThinger struct{ ... }
|
||||
func NewThinger() Thinger { return defaultThinger{ ... } }
|
||||
```
|
||||
|
||||
**不要在接口被使用之前定义它。** 如果没有现实的使用示例，很难判断接口是否真的有必要。
|
||||
|
||||
---
|
||||
|
||||
## 通用性：隐藏实现，暴露接口
|
||||
|
||||
如果一个类型仅用于实现某个接口，且没有该接口之外的导出方法，则从构造函数返回接口以隐藏实现：
|
||||
|
||||
```go
|
||||
func NewHash() hash.Hash32 {
|
||||
return &myHash{} // 未导出的类型
|
||||
}
|
||||
```
|
||||
|
||||
好处：实现可以在不影响调用者的情况下更改，替换算法只需更改构造函数调用。
|
||||
|
||||
---
|
||||
|
||||
## 类型断言：Comma-Ok 模式
|
||||
|
||||
不进行检查的话，失败的断言会导致运行时 panic。始终使用 comma-ok 模式进行安全测试：
|
||||
|
||||
```go
|
||||
str, ok := value.(string)
|
||||
if ok {
|
||||
fmt.Printf("string value is: %q\n", str)
|
||||
}
|
||||
```
|
||||
|
||||
检查值是否实现了某个接口：
|
||||
|
||||
```go
|
||||
if _, ok := val.(json.Marshaler); ok {
|
||||
fmt.Printf("value %v implements json.Marshaler\n", val)
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 类型切换
|
||||
|
||||
重用变量名是惯用做法（`t := t.(type)`）——变量在每个 case 分支中拥有正确的类型。当 case 列出多个类型（`case int, int64:`）时，变量拥有接口类型。
|
||||
|
||||
---
|
||||
|
||||
## 嵌入
|
||||
|
||||
避免在公开结构体中嵌入类型——内部类型的完整方法集将成为你公开 API 的一部分。改用未导出的字段。
|
||||
|
||||
> 在使用结构体嵌入进行组合、重写嵌入方法、解决名称冲突、应用 HandlerFunc 适配器模式或决定是否在公开 API 类型中使用嵌入时，阅读 [references/EMBEDDING.md](references/EMBEDDING.md)。
|
||||
|
||||
---
|
||||
|
||||
## 接口满足检查
|
||||
|
||||
使用空标识符赋值在编译时验证类型是否实现了接口：
|
||||
|
||||
```go
|
||||
var _ json.Marshaler = (*RawMessage)(nil)
|
||||
```
|
||||
|
||||
如果 `*RawMessage` 没有实现 `json.Marshaler`，这会导致编译错误。
|
||||
|
||||
在以下情况下使用此模式：
|
||||
- 没有能自动验证接口的静态转换
|
||||
- 类型必须满足接口才能正确运行（例如自定义 JSON 序列化）
|
||||
- 接口更改应该导致编译失败，而不是静默降级
|
||||
|
||||
**不要**为每个接口都添加这些检查——仅在没有其他静态转换能捕获错误时才使用。
|
||||
|
||||
> **验证**：在定义接口或实现后，运行 `bash scripts/check-interface-compliance.sh` 验证所有具体类型都有编译时的 `var _ I = (*T)(nil)` 检查。
|
||||
|
||||
---
|
||||
|
||||
## 接收者类型
|
||||
|
||||
如果不确定，使用指针接收者。不要在单个类型上混合接收者类型——如果任何方法需要指针，则所有方法都使用指针。仅在小型不可变类型（`Point`、`time.Time`）或基本类型上使用值接收者。
|
||||
|
||||
> 在为新类型决定使用指针接收者还是值接收者时，特别是对于包含 sync 原语或大型结构体的类型，阅读 [references/RECEIVER-TYPE.md](references/RECEIVER-TYPE.md)。
|
||||
|
||||
---
|
||||
|
||||
## 快速参考
|
||||
|
||||
| 概念 | 模式 | 说明 |
|
||||
|------|------|------|
|
||||
| 消费者拥有接口 | 在使用处定义接口 | 不在实现包中 |
|
||||
| 安全类型断言 | `v, ok := x.(Type)` | 返回零值 + false |
|
||||
| 类型切换 | `switch v := x.(type)` | 变量在每个 case 中拥有正确类型 |
|
||||
| 接口嵌入 | `type RW interface { Reader; Writer }` | 方法的并集 |
|
||||
| 结构体嵌入 | `type S struct { *T }` | 提升 T 的方法 |
|
||||
| 接口检查 | `var _ I = (*T)(nil)` | 编译时验证 |
|
||||
| 通用性 | 从构造函数返回接口 | 隐藏实现 |
|
||||
|
||||
---
|
||||
|
||||
## 相关技能
|
||||
|
||||
- **接口命名**：在为接口命名（`-er` 后缀约定）或选择接收者名称时，参见 [go-naming](../go-naming/SKILL.md)
|
||||
- **错误类型**：在实现 `error` 接口、自定义错误类型或 `errors.As` 匹配时，参见 [go-error-handling](../go-error-handling/SKILL.md)
|
||||
- **泛型 vs 接口**：在决定是否需要泛型或接口是否已足够时，参见 [go-generics](../go-generics/SKILL.md)
|
||||
- **函数选项**：在使用基于接口的 Option 模式实现灵活构造函数时，参见 [go-functional-options](../go-functional-options/SKILL.md)
|
||||
- **编译时检查**：在 API 边界添加 `var _ I = (*T)(nil)` 满足检查时，参见 [go-defensive](../go-defensive/SKILL.md)
|
||||
@@ -1,138 +0,0 @@
|
||||
# Go 中的嵌入模式
|
||||
|
||||
> **来源**：Effective Go、Uber 风格指南
|
||||
|
||||
Go 使用嵌入来实现组合而非继承。嵌入将内部类型的方法提升到外部类型，自动满足接口。
|
||||
|
||||
## 接口嵌入
|
||||
|
||||
通过嵌入来组合接口：
|
||||
|
||||
```go
|
||||
type ReadWriter interface {
|
||||
Reader
|
||||
Writer
|
||||
}
|
||||
```
|
||||
|
||||
`ReadWriter` 既能做 `Reader` 能做的事，*也能*做 `Writer` 能做的事。接口中只能嵌入接口。
|
||||
|
||||
## 结构体嵌入
|
||||
|
||||
嵌入将内部类型的方法提升到外部类型，无需显式转发。
|
||||
|
||||
```go
|
||||
type ReadWriter struct {
|
||||
*Reader // *bufio.Reader
|
||||
*Writer // *bufio.Writer
|
||||
}
|
||||
```
|
||||
|
||||
通过嵌入，`bufio.ReadWriter` 自动满足 `io.Reader`、`io.Writer` 和 `io.ReadWriter`。
|
||||
|
||||
混合使用嵌入字段和命名字段：
|
||||
|
||||
```go
|
||||
type Job struct {
|
||||
Command string
|
||||
*log.Logger
|
||||
}
|
||||
|
||||
job.Println("starting now...")
|
||||
job.Logger.SetPrefix("Job: ")
|
||||
```
|
||||
|
||||
## 方法重写
|
||||
|
||||
在外部类型上定义方法以重写提升的方法：
|
||||
|
||||
```go
|
||||
func (job *Job) Printf(format string, args ...any) {
|
||||
job.Logger.Printf("%q: %s", job.Command, fmt.Sprintf(format, args...))
|
||||
}
|
||||
```
|
||||
|
||||
外部方法优先——对 `job.Printf(...)` 的调用会调用外部方法，而嵌入方法仍可通过 `job.Logger.Printf(...)` 访问。
|
||||
|
||||
## 嵌入 vs 子类化
|
||||
|
||||
当调用嵌入方法时，接收者是**内部**类型，而非外部类型。嵌入类型不知道自己被嵌入——不存在类似于 `this` 或 `super` 的引用指向包含它的类型。
|
||||
|
||||
```go
|
||||
type Base struct{}
|
||||
func (b *Base) Name() string { return "Base" }
|
||||
|
||||
type Derived struct{ Base }
|
||||
|
||||
d := Derived{}
|
||||
d.Name() // 返回 "Base"，而非 "Derived"
|
||||
```
|
||||
|
||||
## 名称冲突解决
|
||||
|
||||
1. **外部隐藏内部**——外部类型上的字段或方法会遮蔽嵌入类型在同名位置提升的字段或方法
|
||||
2. **同级冲突是错误**——如果两个同深度的嵌入类型提升了相同的名称，则为编译错误（除非该名称从未被访问）
|
||||
|
||||
```go
|
||||
type A struct{}
|
||||
func (A) Hello() string { return "A" }
|
||||
|
||||
type B struct{}
|
||||
func (B) Hello() string { return "B" }
|
||||
|
||||
type C struct {
|
||||
A
|
||||
B
|
||||
}
|
||||
|
||||
// c.Hello() // 编译错误：选择器不明确
|
||||
c.A.Hello() // 可以：显式消歧
|
||||
```
|
||||
|
||||
## 不要在公开结构体中嵌入
|
||||
|
||||
嵌入将内部类型的完整方法集暴露为你的公开 API 的一部分。这带来了维护负担：嵌入类型方法的更改会破坏 API 的兼容性保证。
|
||||
|
||||
**不好**
|
||||
```go
|
||||
type SMap struct {
|
||||
sync.Mutex // Lock 和 Unlock 现在是 SMap API 的一部分
|
||||
data map[string]string
|
||||
}
|
||||
```
|
||||
|
||||
**好**
|
||||
```go
|
||||
type SMap struct {
|
||||
mu sync.Mutex // 未导出的字段——实现细节
|
||||
data map[string]string
|
||||
}
|
||||
|
||||
func (m *SMap) Get(k string) string {
|
||||
m.mu.Lock()
|
||||
defer m.mu.Unlock()
|
||||
return m.data[k]
|
||||
}
|
||||
```
|
||||
|
||||
例外：在测试类型和 API 稳定性无关紧要的内部结构体中，嵌入是可以接受的。
|
||||
|
||||
## HandlerFunc 适配器模式
|
||||
|
||||
方法可以在任何命名类型上定义，不仅仅是结构体。`http.HandlerFunc` 模式将普通函数转换为接口实现：
|
||||
|
||||
```go
|
||||
type HandlerFunc func(ResponseWriter, *Request)
|
||||
|
||||
func (f HandlerFunc) ServeHTTP(w ResponseWriter, req *Request) {
|
||||
f(w, req)
|
||||
}
|
||||
```
|
||||
|
||||
任何具有正确签名的函数都可以成为 HTTP 处理器：
|
||||
|
||||
```go
|
||||
http.Handle("/args", http.HandlerFunc(ArgServer))
|
||||
```
|
||||
|
||||
这种适配器模式在需要让独立函数满足单方法接口时非常有用。
|
||||
@@ -1,68 +0,0 @@
|
||||
# 接收者类型：指针 vs 值
|
||||
|
||||
> **建议**：Go Wiki CodeReviewComments
|
||||
|
||||
选择在方法上使用值接收者还是指针接收者可能很困难。**如果不确定，使用指针**，但有时值接收者也是合理的。
|
||||
|
||||
## 何时使用指针接收者
|
||||
|
||||
- **方法修改接收者**：接收者必须是指针
|
||||
- **接收者包含 sync.Mutex 或类似类型**：必须使用指针以避免复制
|
||||
- **大型结构体或数组**：指针接收者更高效。如果将所有元素作为参数传递感觉太大，那对值接收者来说也太大了
|
||||
- **并发或被调方法可能修改**：如果更改必须对原始接收者可见，则必须使用指针
|
||||
- **元素是指向可变内容的指针**：优先使用指针接收者使意图更清晰
|
||||
|
||||
## 何时使用值接收者
|
||||
|
||||
- **小型不变的结构体或基本类型**：值接收者以提高效率
|
||||
- **Map、func 或 chan**：不要对它们使用指针
|
||||
- **不重新切片/重新分配的切片**：如果方法不重新切片或重新分配切片，不要使用指针
|
||||
- **没有可变字段的小型值类型**：像 `time.Time` 这样没有可变字段且没有指针的类型适合作为值接收者
|
||||
- **简单基本类型**：`int`、`string` 等
|
||||
|
||||
```go
|
||||
// 值接收者：小型、不可变类型
|
||||
type Point struct {
|
||||
X, Y float64
|
||||
}
|
||||
|
||||
func (p Point) Distance(q Point) float64 {
|
||||
return math.Hypot(q.X-p.X, q.Y-p.Y)
|
||||
}
|
||||
|
||||
// 指针接收者：方法修改接收者
|
||||
func (p *Point) ScaleBy(factor float64) {
|
||||
p.X *= factor
|
||||
p.Y *= factor
|
||||
}
|
||||
|
||||
// 指针接收者：包含 sync.Mutex
|
||||
type Counter struct {
|
||||
mu sync.Mutex
|
||||
count int
|
||||
}
|
||||
|
||||
func (c *Counter) Increment() {
|
||||
c.mu.Lock()
|
||||
c.count++
|
||||
c.mu.Unlock()
|
||||
}
|
||||
```
|
||||
|
||||
## 一致性规则
|
||||
|
||||
**不要混合接收者类型**。为类型上所有可用的方法统一选择指针或结构体类型。如果任何方法需要指针接收者，则所有方法都使用指针接收者。
|
||||
|
||||
```go
|
||||
// 好：一致的指针接收者
|
||||
type Buffer struct {
|
||||
data []byte
|
||||
}
|
||||
|
||||
func (b *Buffer) Write(p []byte) (int, error) { /* ... */ }
|
||||
func (b *Buffer) Read(p []byte) (int, error) { /* ... */ }
|
||||
func (b *Buffer) Len() int { return len(b.data) }
|
||||
|
||||
// 不好：混合接收者类型
|
||||
func (b Buffer) Len() int { return len(b.data) } // 不一致
|
||||
```
|
||||
@@ -1,224 +0,0 @@
|
||||
#!/usr/bin/env bash
|
||||
set -euo pipefail
|
||||
|
||||
VERSION="1.0.0"
|
||||
SCRIPT_NAME="$(basename "$0")"
|
||||
|
||||
usage() {
|
||||
cat <<EOF
|
||||
$SCRIPT_NAME v$VERSION — Check for missing compile-time interface compliance verifications
|
||||
|
||||
USAGE
|
||||
bash $SCRIPT_NAME [options] [path]
|
||||
|
||||
DESCRIPTION
|
||||
Scans Go files for exported interface definitions and checks whether each
|
||||
has a corresponding compile-time compliance assertion like:
|
||||
|
||||
var _ MyInterface = (*MyImpl)(nil)
|
||||
var _ MyInterface = MyImpl{}
|
||||
|
||||
Reports interfaces that lack such compile-time checks. This helps catch
|
||||
interface drift at compile time instead of runtime.
|
||||
|
||||
Exits 0 if all interfaces are verified, 1 if missing checks found, 2 on error.
|
||||
|
||||
OPTIONS
|
||||
-h, --help Show this help message
|
||||
-v, --version Show version
|
||||
--json Output results as JSON
|
||||
--include-test Also scan _test.go files for compliance checks
|
||||
--limit N Show at most N results (default: all)
|
||||
|
||||
ARGUMENTS
|
||||
path Directory to scan (default: current directory)
|
||||
|
||||
EXAMPLES
|
||||
bash $SCRIPT_NAME
|
||||
bash $SCRIPT_NAME ./pkg/storage
|
||||
bash $SCRIPT_NAME --json .
|
||||
bash $SCRIPT_NAME --include-test ./internal
|
||||
EOF
|
||||
}
|
||||
|
||||
JSON_OUTPUT=false
|
||||
INCLUDE_TEST=false
|
||||
LIMIT=0
|
||||
TARGET=""
|
||||
|
||||
while [[ $# -gt 0 ]]; do
|
||||
case "$1" in
|
||||
-h|--help) usage; exit 0 ;;
|
||||
-v|--version) echo "$SCRIPT_NAME v$VERSION"; exit 0 ;;
|
||||
--json) JSON_OUTPUT=true; shift ;;
|
||||
--include-test) INCLUDE_TEST=true; shift ;;
|
||||
--limit) LIMIT="${2:?error: --limit requires a number}"; shift 2 ;;
|
||||
-*) echo "error: unknown option: $1" >&2; usage >&2; exit 2 ;;
|
||||
*) TARGET="$1"; shift ;;
|
||||
esac
|
||||
done
|
||||
|
||||
TARGET="${TARGET:-.}"
|
||||
|
||||
if [[ ! -d "$TARGET" && ! -f "$TARGET" ]]; then
|
||||
# Handle ./... patterns
|
||||
dir="${TARGET%%/...}"
|
||||
dir="${dir:-.}"
|
||||
if [[ ! -d "$dir" ]]; then
|
||||
echo "error: path not found: $TARGET" >&2
|
||||
exit 2
|
||||
fi
|
||||
TARGET="$dir"
|
||||
fi
|
||||
|
||||
json_escape() {
|
||||
local s="$1"
|
||||
s="${s//\\/\\\\}"
|
||||
s="${s//\"/\\\"}"
|
||||
s="${s//$'\t'/\\t}"
|
||||
s="${s//$'\r'/}"
|
||||
s="${s//$'\n'/\\n}"
|
||||
printf '%s' "$s"
|
||||
}
|
||||
|
||||
# Collect all Go source files
|
||||
find_go_files() {
|
||||
local t="$1"
|
||||
if $INCLUDE_TEST; then
|
||||
find "$t" -name '*.go' ! -path '*/vendor/*' ! -path '*/.git/*' 2>/dev/null
|
||||
else
|
||||
find "$t" -name '*.go' ! -name '*_test.go' ! -path '*/vendor/*' ! -path '*/.git/*' 2>/dev/null
|
||||
fi
|
||||
}
|
||||
|
||||
# Collect all Go files (including tests) for checking compliance vars
|
||||
find_all_go_files() {
|
||||
find "$1" -name '*.go' ! -path '*/vendor/*' ! -path '*/.git/*' 2>/dev/null
|
||||
}
|
||||
|
||||
# Step 1: Find all exported interface definitions
|
||||
IFACE_NAMES=()
|
||||
IFACE_LOCATIONS=()
|
||||
|
||||
while IFS= read -r file; do
|
||||
[[ -n "$file" ]] || continue
|
||||
line_num=0
|
||||
while IFS= read -r line; do
|
||||
line_num=$((line_num + 1))
|
||||
# Match: type ExportedName interface {
|
||||
pat='^[[:space:]]*type[[:space:]]+([A-Z][a-zA-Z0-9]*)[[:space:]]+interface[[:space:]]*\{'
|
||||
if [[ "$line" =~ $pat ]]; then
|
||||
iface_name="${BASH_REMATCH[1]}"
|
||||
IFACE_NAMES+=("$iface_name")
|
||||
IFACE_LOCATIONS+=("$file:$line_num")
|
||||
fi
|
||||
done < "$file"
|
||||
done < <(find_go_files "$TARGET")
|
||||
|
||||
if [[ ${#IFACE_NAMES[@]} -eq 0 ]]; then
|
||||
if $JSON_OUTPUT; then
|
||||
echo '{"interfaces":[],"missing":[],"count_interfaces":0,"count_missing":0}'
|
||||
else
|
||||
echo "No exported interfaces found in: $TARGET"
|
||||
fi
|
||||
exit 0
|
||||
fi
|
||||
|
||||
# Step 2: Scan all Go files (including tests) for compliance checks
|
||||
# Pattern: var _ InterfaceName = ...
|
||||
ALL_GO_FILES=()
|
||||
while IFS= read -r f; do
|
||||
[[ -n "$f" ]] && ALL_GO_FILES+=("$f")
|
||||
done < <(find_all_go_files "$TARGET")
|
||||
|
||||
MISSING=()
|
||||
|
||||
for ((i=0; i<${#IFACE_NAMES[@]}; i++)); do
|
||||
iface_name="${IFACE_NAMES[$i]}"
|
||||
location="${IFACE_LOCATIONS[$i]}"
|
||||
# Look for: var _ InterfaceName = (various patterns)
|
||||
if ! grep -qlE "var[[:space:]]+_[[:space:]]+${iface_name}[[:space:]]*=" \
|
||||
"${ALL_GO_FILES[@]}" 2>/dev/null; then
|
||||
MISSING+=("${iface_name}|${location}")
|
||||
fi
|
||||
done
|
||||
|
||||
# Sort for stable output
|
||||
IFS=$'\n' MISSING=($(sort <<<"${MISSING[*]}")); unset IFS
|
||||
|
||||
# Truncation
|
||||
TOTAL=${#MISSING[@]}
|
||||
TRUNCATED=false
|
||||
if [[ $LIMIT -gt 0 && $TOTAL -gt $LIMIT ]]; then
|
||||
MISSING=("${MISSING[@]:0:$LIMIT}")
|
||||
TRUNCATED=true
|
||||
fi
|
||||
|
||||
# Output results
|
||||
if $JSON_OUTPUT; then
|
||||
echo "{"
|
||||
echo ' "interfaces": ['
|
||||
first=true
|
||||
SORTED_INDICES=()
|
||||
for ((i=0; i<${#IFACE_NAMES[@]}; i++)); do
|
||||
SORTED_INDICES+=("$i|${IFACE_NAMES[$i]}")
|
||||
done
|
||||
IFS=$'\n' SORTED_INDICES=($(sort -t'|' -k2 <<<"${SORTED_INDICES[*]}")); unset IFS
|
||||
|
||||
for entry in "${SORTED_INDICES[@]}"; do
|
||||
i="${entry%%|*}"
|
||||
iface_name="${IFACE_NAMES[$i]}"
|
||||
location="${IFACE_LOCATIONS[$i]}"
|
||||
file="${location%%:*}"
|
||||
line="${location#*:}"
|
||||
$first || echo ","
|
||||
first=false
|
||||
printf ' {"name":"%s","file":"%s","line":%s}' "$(json_escape "$iface_name")" "$(json_escape "$file")" "$line"
|
||||
done
|
||||
echo ""
|
||||
echo " ],"
|
||||
echo ' "missing": ['
|
||||
first=true
|
||||
for entry in "${MISSING[@]+"${MISSING[@]}"}"; do
|
||||
IFS='|' read -r name location <<< "$entry"
|
||||
file="${location%%:*}"
|
||||
line="${location#*:}"
|
||||
$first || echo ","
|
||||
first=false
|
||||
printf ' {"name":"%s","file":"%s","line":%s}' "$(json_escape "$name")" "$(json_escape "$file")" "$line"
|
||||
done
|
||||
echo ""
|
||||
echo " ],"
|
||||
printf ' "count_interfaces": %d,\n' "${#IFACE_NAMES[@]}"
|
||||
printf ' "count_missing": %d,\n' "$TOTAL"
|
||||
printf ' "truncated": %s\n' "$TRUNCATED"
|
||||
echo "}"
|
||||
else
|
||||
echo "Exported interfaces found: ${#IFACE_NAMES[@]}"
|
||||
echo ""
|
||||
|
||||
if [[ $TOTAL -eq 0 ]]; then
|
||||
echo "All interfaces have compile-time compliance checks."
|
||||
exit 0
|
||||
fi
|
||||
|
||||
echo "Missing compile-time compliance checks:"
|
||||
echo ""
|
||||
for entry in "${MISSING[@]}"; do
|
||||
IFS='|' read -r name location <<< "$entry"
|
||||
printf " %s interface '%s' has no 'var _ %s = ...' assertion\n" "$location" "$name" "$name"
|
||||
done
|
||||
if $TRUNCATED; then
|
||||
echo " ... and $((TOTAL - LIMIT)) more (use --limit to adjust)"
|
||||
fi
|
||||
echo ""
|
||||
echo "Add compile-time checks like:"
|
||||
echo " var _ MyInterface = (*MyImpl)(nil)"
|
||||
echo ""
|
||||
echo "Total: $TOTAL interface(s) missing verification"
|
||||
fi
|
||||
|
||||
if [[ $TOTAL -gt 0 ]]; then
|
||||
exit 1
|
||||
fi
|
||||
exit 0
|
||||
@@ -1,209 +0,0 @@
|
||||
---
|
||||
name: go-linting
|
||||
description: Use when setting up linting for a Go project, configuring golangci-lint, or adding Go checks to a CI/CD pipeline. Also use when starting a new Go project and deciding which linters to enable, even if the user only asks about "code quality" or "static analysis" without mentioning specific linter names. Does not cover code review process (see go-code-review).
|
||||
license: Apache-2.0
|
||||
metadata:
|
||||
sources: "Uber Style Guide"
|
||||
allowed-tools: Bash(bash:*)
|
||||
---
|
||||
|
||||
# Go Lint
|
||||
|
||||
## 核心原则
|
||||
|
||||
比任何"推荐"的 linter 集合更重要的是：**在整个代码库中一致地进行 lint**。
|
||||
|
||||
一致的 lint 有助于捕获常见问题，并在不过度限制的情况下建立高标准的代码质量。
|
||||
|
||||
---
|
||||
|
||||
## 设置步骤
|
||||
|
||||
1. 使用下面的配置创建 `.golangci.yml`
|
||||
2. 运行 `golangci-lint run ./...`
|
||||
3. 如果出现错误，按类别逐一修复（先格式化，再 vet，再风格）
|
||||
4. 重新运行直到通过
|
||||
|
||||
---
|
||||
|
||||
## 最低推荐 Linter
|
||||
|
||||
这些 linter 能捕获最常见的问题，同时保持高质量标准：
|
||||
|
||||
| Linter | 用途 |
|
||||
|--------|------|
|
||||
| [errcheck](https://github.com/kisielk/errcheck) | 确保错误被处理 |
|
||||
| [goimports](https://pkg.go.dev/golang.org/x/tools/cmd/goimports) | 格式化代码和管理导入 |
|
||||
| [revive](https://github.com/mgechev/revive) | 常见风格错误（golint 的现代替代品） |
|
||||
| [govet](https://pkg.go.dev/cmd/vet) | 分析代码中的常见错误 |
|
||||
| [staticcheck](https://staticcheck.dev) | 各种静态分析检查 |
|
||||
|
||||
> **注意**：`revive` 是现已弃用的 `golint` 的现代、更快的替代品。
|
||||
|
||||
---
|
||||
|
||||
## Lint 运行器：golangci-lint
|
||||
|
||||
使用 [golangci-lint](https://github.com/golangci/golangci-lint) 作为你的 lint 运行器。参见 uber-go/guide 的 [示例 .golangci.yml](https://github.com/uber-go/guide/blob/master/.golangci.yml)。
|
||||
|
||||
---
|
||||
|
||||
## 示例配置
|
||||
|
||||
> 在创建新的 `.golangci.yml` 或将现有配置与推荐基线进行比较时，参见 `assets/golangci.yml`。
|
||||
|
||||
在项目根目录创建 `.golangci.yml`：
|
||||
|
||||
```yaml
|
||||
linters:
|
||||
enable:
|
||||
- errcheck
|
||||
- goimports
|
||||
- revive
|
||||
- govet
|
||||
- staticcheck
|
||||
|
||||
linters-settings:
|
||||
goimports:
|
||||
local-prefixes: github.com/your-org/your-repo
|
||||
revive:
|
||||
rules:
|
||||
- name: blank-imports
|
||||
- name: context-as-argument
|
||||
- name: error-return
|
||||
- name: error-strings
|
||||
- name: exported
|
||||
|
||||
run:
|
||||
timeout: 5m
|
||||
```
|
||||
|
||||
### 运行
|
||||
|
||||
```bash
|
||||
# 安装
|
||||
go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest
|
||||
|
||||
# 运行所有 linter
|
||||
golangci-lint run
|
||||
|
||||
# 对特定路径运行
|
||||
golangci-lint run ./pkg/...
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 额外推荐的 Linter
|
||||
|
||||
除了最低集合之外，在生产项目中可以考虑以下 linter：
|
||||
|
||||
| Linter | 用途 | 何时启用 |
|
||||
|--------|------|----------|
|
||||
| [gosec](https://github.com/securego/gosec) | 安全漏洞检测 | 处理用户输入的服务始终启用 |
|
||||
| [ineffassign](https://github.com/gordonklaus/ineffassign) | 检测无效赋值 | 始终——捕获死代码 |
|
||||
| [misspell](https://github.com/client9/misspell) | 纠正注释/字符串中的常见拼写错误 | 始终 |
|
||||
| [gocyclo](https://github.com/fzipp/gocyclo) | 圈复杂度阈值 | 当函数超过约 15 的复杂度时 |
|
||||
| [exhaustive](https://github.com/nishanths/exhaustive) | 确保 switch 覆盖所有枚举值 | 使用 iota 枚举时 |
|
||||
| [bodyclose](https://github.com/timakin/bodyclose) | 检测未关闭的 HTTP 响应体 | HTTP 客户端代码始终启用 |
|
||||
|
||||
---
|
||||
|
||||
## Nolint 指令
|
||||
|
||||
在抑制 lint 发现时，始终说明原因：
|
||||
|
||||
```go
|
||||
//nolint:errcheck // 即发即忘的日志；错误不可操作
|
||||
_ = logger.Sync()
|
||||
```
|
||||
|
||||
规则：
|
||||
- 使用 `//nolint:lintername`——永远不要使用裸 `//nolint`
|
||||
- 将注释放在与发现相同的行
|
||||
- 在 `//` 之后包含理由说明
|
||||
|
||||
---
|
||||
|
||||
## CI/CD 集成
|
||||
|
||||
### GitHub Actions
|
||||
|
||||
```yaml
|
||||
# .github/workflows/lint.yml
|
||||
name: Lint
|
||||
on: [push, pull_request]
|
||||
jobs:
|
||||
lint:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
- uses: actions/setup-go@v5
|
||||
with:
|
||||
go-version: stable
|
||||
- uses: golangci/golangci-lint-action@v6
|
||||
with:
|
||||
version: latest
|
||||
```
|
||||
|
||||
### Pre-commit Hook
|
||||
|
||||
```bash
|
||||
#!/bin/sh
|
||||
# .git/hooks/pre-commit
|
||||
golangci-lint run --new-from-rev=HEAD~1
|
||||
```
|
||||
|
||||
使用 `--new-from-rev` 只对更改的代码进行 lint，保持快速反馈循环。
|
||||
|
||||
---
|
||||
|
||||
## 可用脚本
|
||||
|
||||
- **`scripts/setup-lint.sh`**——生成 `.golangci.yml` 并运行初始 lint
|
||||
|
||||
```bash
|
||||
bash scripts/setup-lint.sh github.com/your-org/your-repo
|
||||
bash scripts/setup-lint.sh --force github.com/your-org/your-repo # 覆盖现有配置
|
||||
bash scripts/setup-lint.sh --dry-run # 预览配置
|
||||
bash scripts/setup-lint.sh --json # 结构化输出
|
||||
```
|
||||
|
||||
> **验证**：在生成 `.golangci.yml` 后，运行 `golangci-lint run ./...` 验证配置有效并产生预期输出。如果因配置错误而失败，修复后重试。
|
||||
|
||||
> `scripts/setup-lint.sh` 生成**最低**配置（5 个核心 linter）。
|
||||
> 对于已有项目，使用 `assets/golangci.yml` 作为起点——
|
||||
> 它增加了 gosec、ineffassign、misspell、gocyclo 和 bodyclose。
|
||||
|
||||
---
|
||||
|
||||
## 快速参考
|
||||
|
||||
| 任务 | 命令/操作 |
|
||||
|------|-----------|
|
||||
| 安装 golangci-lint | `go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest` |
|
||||
| 运行 linter | `golangci-lint run` |
|
||||
| 对路径运行 | `golangci-lint run ./pkg/...` |
|
||||
| 配置文件 | 项目根目录的 `.golangci.yml` |
|
||||
| CI 集成 | 在管道中运行 `golangci-lint run` |
|
||||
| Nolint 指令 | `//nolint:name // 原因`——永远不要使用裸 `//nolint` |
|
||||
| CI 集成 | 使用 `golangci/golangci-lint-action` 用于 GitHub Actions |
|
||||
| Pre-commit | `golangci-lint run --new-from-rev=HEAD~1` |
|
||||
|
||||
### Linter 选择指南
|
||||
|
||||
| 当你需要... | 使用 |
|
||||
|-------------|------|
|
||||
| 错误处理覆盖率 | errcheck |
|
||||
| 导入格式化 | goimports |
|
||||
| 风格一致性 | revive |
|
||||
| Bug 检测 | govet、staticcheck |
|
||||
| 以上全部 | golangci-lint 配合配置 |
|
||||
|
||||
---
|
||||
|
||||
## 相关技能
|
||||
|
||||
- **风格基础**：在解决 linter 执行的风格问题（格式化、嵌套、命名）时，参见 [go-style-core](../go-style-core/SKILL.md)
|
||||
- **代码审查**：在将 linter 输出与手动审查清单结合使用时，参见 [go-code-review](../go-code-review/SKILL.md)
|
||||
- **错误处理**：在 errcheck 标记未处理的错误并需要决定如何处理时，参见 [go-error-handling](../go-error-handling/SKILL.md)
|
||||
- **测试**：在 CI 管道中将 linter 与测试一起运行时，参见 [go-testing](../go-testing/SKILL.md)
|
||||
@@ -1,31 +0,0 @@
|
||||
run:
|
||||
timeout: 5m
|
||||
|
||||
linters:
|
||||
enable:
|
||||
# Minimum recommended
|
||||
- errcheck
|
||||
- goimports
|
||||
- revive
|
||||
- govet
|
||||
- staticcheck
|
||||
# Additional recommended
|
||||
- gosec
|
||||
- ineffassign
|
||||
- misspell
|
||||
- gocyclo
|
||||
- bodyclose
|
||||
|
||||
linters-settings:
|
||||
goimports:
|
||||
local-prefixes: "" # Set to your module path
|
||||
revive:
|
||||
rules:
|
||||
- name: exported
|
||||
gocyclo:
|
||||
min-complexity: 15
|
||||
|
||||
issues:
|
||||
exclude-use-default: false
|
||||
max-issues-per-linter: 0
|
||||
max-same-issues: 0
|
||||
@@ -1,172 +0,0 @@
|
||||
#!/usr/bin/env bash
|
||||
set -euo pipefail
|
||||
|
||||
VERSION="1.0.0"
|
||||
SCRIPT_NAME="$(basename "$0")"
|
||||
|
||||
usage() {
|
||||
cat <<EOF
|
||||
$SCRIPT_NAME v$VERSION — Generate .golangci.yml and run initial lint
|
||||
|
||||
USAGE
|
||||
bash $SCRIPT_NAME [options] [local-prefix]
|
||||
|
||||
DESCRIPTION
|
||||
Creates a .golangci.yml with a curated set of linters (errcheck,
|
||||
goimports, revive, govet, staticcheck) and runs golangci-lint.
|
||||
If local-prefix is provided, configures goimports to group local
|
||||
imports separately.
|
||||
|
||||
Exits 0 if lint passes, 1 if lint issues found, 2 on error.
|
||||
|
||||
OPTIONS
|
||||
-h, --help Show this help message
|
||||
-v, --version Show version
|
||||
--json Output results as JSON
|
||||
--force Overwrite existing .golangci.yml
|
||||
--dry-run Print generated config to stdout without writing
|
||||
--limit N Max lint issue lines in JSON output (default: 50, 0 = unlimited)
|
||||
|
||||
ARGUMENTS
|
||||
local-prefix Module path prefix for goimports grouping
|
||||
(e.g., github.com/myorg/myrepo)
|
||||
|
||||
EXAMPLES
|
||||
bash $SCRIPT_NAME
|
||||
bash $SCRIPT_NAME github.com/myorg/myrepo
|
||||
bash $SCRIPT_NAME --force github.com/myorg/myrepo
|
||||
bash $SCRIPT_NAME --dry-run github.com/myorg/myrepo
|
||||
bash $SCRIPT_NAME --json
|
||||
bash $SCRIPT_NAME --json --limit 20
|
||||
EOF
|
||||
}
|
||||
|
||||
json_escape() {
|
||||
local s="$1"
|
||||
s="${s//\\/\\\\}"
|
||||
s="${s//\"/\\\"}"
|
||||
s="${s//$'\t'/\\t}"
|
||||
s="${s//$'\r'/}"
|
||||
s="${s//$'\n'/\\n}"
|
||||
printf '%s' "$s"
|
||||
}
|
||||
|
||||
JSON_OUTPUT=false
|
||||
FORCE=false
|
||||
DRY_RUN=false
|
||||
LIMIT=50
|
||||
LOCAL_PREFIX=""
|
||||
|
||||
while [[ $# -gt 0 ]]; do
|
||||
case "$1" in
|
||||
-h|--help) usage; exit 0 ;;
|
||||
-v|--version) echo "$SCRIPT_NAME v$VERSION"; exit 0 ;;
|
||||
--json) JSON_OUTPUT=true; shift ;;
|
||||
--force) FORCE=true; shift ;;
|
||||
--dry-run) DRY_RUN=true; shift ;;
|
||||
--limit) LIMIT="${2:?error: --limit requires a number}"; shift 2 ;;
|
||||
-*) echo "error: unknown option: $1" >&2; usage >&2; exit 2 ;;
|
||||
*) LOCAL_PREFIX="$1"; shift ;;
|
||||
esac
|
||||
done
|
||||
|
||||
generate_config() {
|
||||
cat <<'YAML'
|
||||
linters:
|
||||
enable:
|
||||
- errcheck
|
||||
- goimports
|
||||
- revive
|
||||
- govet
|
||||
- staticcheck
|
||||
|
||||
linters-settings:
|
||||
YAML
|
||||
|
||||
if [[ -n "$LOCAL_PREFIX" ]]; then
|
||||
cat <<YAML
|
||||
goimports:
|
||||
local-prefixes: ${LOCAL_PREFIX}
|
||||
YAML
|
||||
fi
|
||||
|
||||
cat <<'YAML'
|
||||
revive:
|
||||
rules:
|
||||
- name: blank-imports
|
||||
- name: context-as-argument
|
||||
- name: error-return
|
||||
- name: error-strings
|
||||
- name: exported
|
||||
|
||||
run:
|
||||
timeout: 5m
|
||||
YAML
|
||||
}
|
||||
|
||||
if $DRY_RUN; then
|
||||
generate_config
|
||||
exit 0
|
||||
fi
|
||||
|
||||
CONFIG_PATH=".golangci.yml"
|
||||
|
||||
if [[ -f "$CONFIG_PATH" ]] && ! $FORCE; then
|
||||
echo "error: $CONFIG_PATH already exists (use --force to overwrite)" >&2
|
||||
exit 2
|
||||
fi
|
||||
|
||||
generate_config > "$CONFIG_PATH"
|
||||
|
||||
LINT_OUTPUT=""
|
||||
LINT_EXIT=0
|
||||
if ! command -v golangci-lint &>/dev/null; then
|
||||
echo "error: golangci-lint is not installed" >&2
|
||||
exit 2
|
||||
fi
|
||||
|
||||
LINT_OUTPUT=$(golangci-lint run ./... 2>&1) || LINT_EXIT=$?
|
||||
|
||||
if $JSON_OUTPUT; then
|
||||
LINT_TRUNCATED=false
|
||||
LINT_DISPLAY="$LINT_OUTPUT"
|
||||
if [[ $LIMIT -gt 0 && -n "$LINT_OUTPUT" ]]; then
|
||||
LINT_ARR=()
|
||||
while IFS= read -r line; do
|
||||
LINT_ARR+=("$line")
|
||||
done <<< "$LINT_OUTPUT"
|
||||
if [[ ${#LINT_ARR[@]} -gt $LIMIT ]]; then
|
||||
LINT_DISPLAY=""
|
||||
for (( i=0; i<LIMIT; i++ )); do
|
||||
[[ -n "$LINT_DISPLAY" ]] && LINT_DISPLAY+=$'\n'
|
||||
LINT_DISPLAY+="${LINT_ARR[$i]}"
|
||||
done
|
||||
LINT_TRUNCATED=true
|
||||
fi
|
||||
fi
|
||||
LINT_ESC="$(json_escape "$LINT_DISPLAY")"
|
||||
CONFIG_ESC="$(json_escape "$CONFIG_PATH")"
|
||||
PREFIX_ESC="$(json_escape "$LOCAL_PREFIX")"
|
||||
CREATED=true
|
||||
HAS_ISSUES=$( [[ $LINT_EXIT -ne 0 ]] && echo true || echo false )
|
||||
TRUNC_FIELD=""
|
||||
$LINT_TRUNCATED && TRUNC_FIELD=',"truncated":true'
|
||||
cat <<EOF
|
||||
{"config_path":"$CONFIG_ESC","local_prefix":"$PREFIX_ESC","created":$CREATED,"lint_issues":$HAS_ISSUES,"lint_output":"$LINT_ESC"$TRUNC_FIELD}
|
||||
EOF
|
||||
else
|
||||
echo "Created $CONFIG_PATH"
|
||||
if [[ $LINT_EXIT -ne 0 ]]; then
|
||||
echo ""
|
||||
echo "$LINT_OUTPUT"
|
||||
echo ""
|
||||
echo "Lint issues found — fix them category by category (formatting first, then vet, then style)."
|
||||
else
|
||||
echo "golangci-lint: all clean."
|
||||
fi
|
||||
fi
|
||||
|
||||
if [[ $LINT_EXIT -ne 0 ]]; then
|
||||
exit 1
|
||||
fi
|
||||
exit 0
|
||||
@@ -1,179 +0,0 @@
|
||||
---
|
||||
name: go-style-core
|
||||
description: Use when working with Go formatting, line length, nesting, naked returns, semicolons, or core style principles. Also use when a style question isn't covered by a more specific skill, even if the user doesn't reference a specific style rule. Does not cover domain-specific patterns like error handling, naming, or testing (see specialized skills). Acts as fallback when no more specific style skill applies.
|
||||
license: Apache-2.0
|
||||
metadata:
|
||||
sources: "Effective Go, Google Style Guide, Uber Style Guide, Go Wiki CodeReviewComments"
|
||||
---
|
||||
|
||||
# Go 风格核心原则
|
||||
|
||||
## 风格原则（优先级顺序）
|
||||
|
||||
编写可读 Go 代码时，按以下重要性顺序应用这些原则：
|
||||
|
||||
### 优先级顺序
|
||||
|
||||
1. **清晰性** — 读者能否在没有额外上下文的情况下理解代码？
|
||||
2. **简洁性** — 这是否是实现目标的最简单方式？
|
||||
3. **精炼性** — 每一行是否都有其存在的价值？
|
||||
4. **可维护性** — 后续修改是否容易？
|
||||
5. **一致性** — 是否与周围代码和项目约定保持一致？
|
||||
|
||||
> 在解决清晰性、简洁性和精炼性之间的冲突时，或需要具体示例了解每个原则在实际 Go 代码中的应用时，请阅读 [references/PRINCIPLES.md](references/PRINCIPLES.md)。
|
||||
|
||||
---
|
||||
|
||||
## 格式化
|
||||
|
||||
运行 `gofmt` — 没有例外。**没有严格的行长度限制**，但 Uber 建议软限制为 99 个字符。按语义换行，而非按长度 — 选择重构而非仅仅换行。
|
||||
|
||||
> 在配置 gofmt、决定换行策略、应用 MixedCaps 规则或解决局部一致性问题时，请阅读 [references/FORMATTING.md](references/FORMATTING.md)。
|
||||
|
||||
---
|
||||
|
||||
## 减少嵌套
|
||||
|
||||
优先处理错误情况和特殊条件。提前返回或继续循环，使"正常路径"保持无缩进。
|
||||
|
||||
```go
|
||||
// 不好：深度嵌套
|
||||
for _, v := range data {
|
||||
if v.F1 == 1 {
|
||||
v = process(v)
|
||||
if err := v.Call(); err == nil {
|
||||
v.Send()
|
||||
} else {
|
||||
return err
|
||||
}
|
||||
} else {
|
||||
log.Printf("Invalid v: %v", v)
|
||||
}
|
||||
}
|
||||
|
||||
// 好：扁平结构，提前返回
|
||||
for _, v := range data {
|
||||
if v.F1 != 1 {
|
||||
log.Printf("Invalid v: %v", v)
|
||||
continue
|
||||
}
|
||||
|
||||
v = process(v)
|
||||
if err := v.Call(); err != nil {
|
||||
return err
|
||||
}
|
||||
v.Send()
|
||||
}
|
||||
```
|
||||
|
||||
### 不必要的 Else
|
||||
|
||||
如果变量在 if 的两个分支中都被赋值，使用默认值 + 覆盖模式。
|
||||
|
||||
```go
|
||||
// 不好：在两个分支中都赋值
|
||||
var a int
|
||||
if b {
|
||||
a = 100
|
||||
} else {
|
||||
a = 10
|
||||
}
|
||||
|
||||
// 好：默认值 + 覆盖
|
||||
a := 10
|
||||
if b {
|
||||
a = 100
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 裸返回
|
||||
|
||||
没有参数的 `return` 语句会返回命名返回值。这被称为"裸"返回。
|
||||
|
||||
```go
|
||||
func split(sum int) (x, y int) {
|
||||
x = sum * 4 / 9
|
||||
y = sum - x
|
||||
return // 返回 x, y
|
||||
}
|
||||
```
|
||||
|
||||
### 裸返回的使用指南
|
||||
|
||||
- **在小型函数中可以使用**：裸返回在只有几行的函数中是没问题的
|
||||
- **在中大型函数中要明确**：一旦函数增长到中等大小，为了清晰起见应明确指定返回值
|
||||
- **不要仅为了裸返回而命名返回值**：文档的清晰性始终比节省一两行更重要
|
||||
|
||||
```go
|
||||
// 好：小型函数，裸返回很清晰
|
||||
func minMax(a, b int) (min, max int) {
|
||||
if a < b {
|
||||
min, max = a, b
|
||||
} else {
|
||||
min, max = b, a
|
||||
}
|
||||
return
|
||||
}
|
||||
|
||||
// 好：较大的函数，显式返回
|
||||
func processData(data []byte) (result []byte, err error) {
|
||||
result = make([]byte, 0, len(data))
|
||||
|
||||
for _, b := range data {
|
||||
if b == 0 {
|
||||
return nil, errors.New("null byte in data")
|
||||
}
|
||||
result = append(result, transform(b))
|
||||
}
|
||||
|
||||
return result, nil // 显式返回：在较长的函数中更清晰
|
||||
}
|
||||
```
|
||||
|
||||
关于命名返回参数的指导，请参阅 **go-documentation**。
|
||||
|
||||
---
|
||||
|
||||
## 分号
|
||||
|
||||
Go 的词法分析器会在任何最后一个 token 是标识符、字面量或以下关键字之一的行后自动插入分号：`break continue fallthrough return ++ -- ) }`。
|
||||
|
||||
这意味着 **左花括号必须与控制结构在同一行**：
|
||||
|
||||
```go
|
||||
// 好：花括号在同一行
|
||||
if i < f() {
|
||||
g()
|
||||
}
|
||||
|
||||
// 不好：花括号在下一行 — 词法分析器会在 f() 后插入分号
|
||||
if i < f() // 错误！
|
||||
{ // 错误！
|
||||
g()
|
||||
}
|
||||
```
|
||||
|
||||
在惯用 Go 中，显式分号仅出现在 `for` 循环子句中和用于分隔单行上的多个语句。
|
||||
|
||||
---
|
||||
|
||||
## 快速参考
|
||||
|
||||
| 原则 | 核心问题 |
|
||||
|------|----------|
|
||||
| 清晰性 | 读者能否理解代码的意图和原因？ |
|
||||
| 简洁性 | 这是否是最简单的方法？ |
|
||||
| 精炼性 | 信噪比是否高？ |
|
||||
| 可维护性 | 后续能否安全地修改？ |
|
||||
| 一致性 | 是否与周围代码保持一致？ |
|
||||
|
||||
## 相关 Skill
|
||||
|
||||
- **命名约定**：在应用 MixedCaps、选择标识符名称或解决命名争议时，请参阅 [go-naming](../go-naming/SKILL.md)
|
||||
- **错误流程**：在构建错误优先的守卫子句或通过提前返回减少嵌套时，请参阅 [go-error-handling](../go-error-handling/SKILL.md)
|
||||
- **文档**：在编写文档注释、命名返回参数或包级别文档时，请参阅 [go-documentation](../go-documentation/SKILL.md)
|
||||
- **Linting 执行**：在使用 golangci-lint 自动化风格检查或配置 CI 时，请参阅 [go-linting](../go-linting/SKILL.md)
|
||||
- **代码审查**：在系统性代码审查中应用风格原则时，请参阅 [go-code-review](../go-code-review/SKILL.md)
|
||||
- **日志风格**：在审查日志实践、在 log 和 slog 之间选择或组织日志输出时，请参阅 [go-logging](../go-logging/SKILL.md)
|
||||
@@ -1,95 +0,0 @@
|
||||
# 格式化参考
|
||||
|
||||
## gofmt 是必须的
|
||||
|
||||
所有 Go 源文件 **必须** 符合 `gofmt` 的输出。没有例外。
|
||||
|
||||
```bash
|
||||
# 格式化一个文件
|
||||
gofmt -w myfile.go
|
||||
|
||||
# 格式化目录下所有文件
|
||||
gofmt -w .
|
||||
```
|
||||
|
||||
其他格式化工具：
|
||||
|
||||
| 工具 | 用途 |
|
||||
|------|------|
|
||||
| `gofmt` | 标准格式化工具（必须使用） |
|
||||
| `goimports` | gofmt + import 管理 |
|
||||
| `gofumpt` | gofmt 的更严格超集 |
|
||||
|
||||
---
|
||||
|
||||
## 括号
|
||||
|
||||
Go 比 C 和 Java 需要更少的括号。控制结构（`if`、`for`、`switch`）的语法中不需要括号。运算符优先级层次更短更清晰，所以 `x<<8 + y<<16` 的含义就如空格所暗示的那样 — 不像其他语言。
|
||||
|
||||
---
|
||||
|
||||
## MixedCaps（驼峰命名）
|
||||
|
||||
Go 使用 `MixedCaps` 或 `mixedCaps`，从不使用下划线：
|
||||
|
||||
```go
|
||||
// 好
|
||||
MaxLength // 导出常量
|
||||
maxLength // 非导出常量
|
||||
userID // 变量
|
||||
|
||||
// 不好
|
||||
MAX_LENGTH // 不使用 snake_case
|
||||
max_length // 不使用下划线
|
||||
```
|
||||
|
||||
例外：
|
||||
- 测试函数名可以使用下划线：`TestFoo_Bar`
|
||||
- 与 OS/cgo 交互的生成代码
|
||||
|
||||
---
|
||||
|
||||
## 行长度
|
||||
|
||||
Go 中 **没有严格的行长度限制**，但避免过长的行。Uber 建议软限制为 99 个字符。
|
||||
|
||||
指导原则：
|
||||
- 如果一行感觉太长，**重构** 而非仅仅换行
|
||||
- 不要在缩进变化之前换行（函数声明、条件语句）
|
||||
- 不要将长字符串（URL）拆分成多行
|
||||
- 换行时，将所有参数放在各自的行上
|
||||
- 如果已经尽可能短了，就让它保持长行
|
||||
|
||||
**按语义换行，而非按长度**：
|
||||
|
||||
不要仅仅为了保持短行而添加换行符，当长行更具可读性时（例如，重复性的行）。因为你所写的内容而换行，而非因为行长度。
|
||||
|
||||
长行通常与长名称相关。如果你发现行太长，考虑名称是否可以更短。去掉长名称往往比换行更有帮助。
|
||||
|
||||
这个建议同样适用于函数长度 — 没有"函数永远不超过 N 行"的规则，但确实存在太长的情况。解决方案是改变函数的边界在哪里，而非计算行数。
|
||||
|
||||
```go
|
||||
// 不好：随意的行中断
|
||||
func (s *Store) GetUser(ctx context.Context,
|
||||
id string) (*User, error) {
|
||||
|
||||
// 好：所有参数各占一行
|
||||
func (s *Store) GetUser(
|
||||
ctx context.Context,
|
||||
id string,
|
||||
) (*User, error) {
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 局部一致性
|
||||
|
||||
当风格指南未做规定时，与附近代码保持一致：
|
||||
|
||||
**有效的** 局部选择：
|
||||
- 错误格式化使用 `%s` 还是 `%v`
|
||||
- 带缓冲 channel 还是 mutex
|
||||
|
||||
**无效的** 局部覆盖：
|
||||
- 行长度限制
|
||||
- 基于断言的测试库
|
||||
@@ -1,89 +0,0 @@
|
||||
# 风格原则参考
|
||||
|
||||
## 1. 清晰性
|
||||
|
||||
代码的目的和原理必须对读者清晰。
|
||||
|
||||
- **做什么**：使用描述性名称、有帮助的注释和高效的组织
|
||||
- **为什么**：添加解释原理的注释，特别是对于微妙的细节
|
||||
- 从读者的角度审视清晰性，而非作者的角度
|
||||
- 代码应该易于阅读，而非易于编写
|
||||
|
||||
```go
|
||||
// 好：目的清晰
|
||||
func (c *Config) WriteTo(w io.Writer) (int64, error)
|
||||
|
||||
// 不好：不清晰，重复了接收者
|
||||
func (c *Config) WriteConfigTo(w io.Writer) (int64, error)
|
||||
```
|
||||
|
||||
## 2. 简洁性
|
||||
|
||||
代码应该以最简单的方式实现目标。
|
||||
|
||||
简洁的代码：
|
||||
- 从头到尾容易阅读
|
||||
- 不假定读者有先验知识
|
||||
- 没有不必要的抽象层次
|
||||
- 注释解释"为什么"，而非"做什么"
|
||||
- 可能与"巧妙"的代码互斥
|
||||
|
||||
### 最少机制
|
||||
|
||||
当有几种方式表达同一个想法时，优先使用最标准的工具：
|
||||
|
||||
1. 核心语言结构（channel、slice、map、loop、struct）
|
||||
2. 标准库（HTTP 客户端、模板引擎）
|
||||
3. 第三方库 — 仅在 (1) 和 (2) 不够用时使用
|
||||
|
||||
## 3. 精炼性
|
||||
|
||||
代码应该有高信噪比。
|
||||
|
||||
- 避免重复代码
|
||||
- 避免多余的语法
|
||||
- 避免不必要的抽象
|
||||
- 使用表驱动测试提取公共代码
|
||||
|
||||
```go
|
||||
// 好：常见惯用法，信号量高
|
||||
if err := doSomething(); err != nil {
|
||||
return err
|
||||
}
|
||||
|
||||
// 好：为异常情况增强信号
|
||||
if err := doSomething(); err == nil { // 如果没有错误
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
## 4. 可维护性
|
||||
|
||||
代码被修改的次数远多于被编写的次数。
|
||||
|
||||
可维护的代码：
|
||||
- 对于未来的程序员来说容易正确修改
|
||||
- API 能够优雅地扩展
|
||||
- 使用可预测的名称（相同概念 = 相同名称）
|
||||
- 最小化依赖
|
||||
- 具有全面的测试和清晰的诊断信息
|
||||
|
||||
```go
|
||||
// 不好：关键细节被隐藏
|
||||
if user, err = db.UserByID(userID); err != nil { // = vs :=
|
||||
|
||||
// 好：显式且清晰
|
||||
u, err := db.UserByID(userID)
|
||||
if err != nil {
|
||||
return fmt.Errorf("invalid origin user: %s", err)
|
||||
}
|
||||
user = u
|
||||
```
|
||||
|
||||
## 5. 一致性
|
||||
|
||||
代码的外观和行为应该与代码库中的类似代码一致。
|
||||
|
||||
- 包级别的一致性最重要
|
||||
- 当出现平局时，优先保持一致性
|
||||
- 绝不为了局部一致性而覆盖有文档记录的风格原则
|
||||
@@ -1,37 +0,0 @@
|
||||
---
|
||||
name: plan
|
||||
description: 项目级技能：规定在开启新方案、新计划或进行任务交接时，必须将计划落库到 docs/plan 文件夹中并使用对应模板。
|
||||
---
|
||||
|
||||
# Plan & Handover Skill
|
||||
|
||||
当你在当前项目中被要求“开启一个新的方案”、“制定开发计划”或者准备“任务交接（Handover）”时，你**必须**遵循本技能的工作流，将计划或方案落库到 `docs/plan/` 目录下。
|
||||
|
||||
> [!IMPORTANT]
|
||||
> **什么时候应当创建实现计划？**
|
||||
> * **必须创建的场景**：新功能开发、涉及多组件的重大架构重构、引入新基础设施依赖，以及存在显著设计决策冲突的**中大型、复杂**需求。
|
||||
> * **绝对不要创建的场景**：改个包名、挪个文件、重命名函数、小修小改修复 Bug 等**轻量级、简单的局部重构**。对于此类改动，应当直接完成并运行单元测试通过后交付，禁止制造冗余的计划文档。
|
||||
|
||||
## 执行工作流 (Workflow)
|
||||
|
||||
### 1. 确定计划类型
|
||||
* **新特性/技术实现计划**：如果你要开发新功能或进行重大重构，你需要创建**实现计划**。
|
||||
* **AI 任务交接计划**：如果当前任务尚未完成但需要记录进度留作以后或其他 AI 代理接手，你需要创建**交接计划**。
|
||||
|
||||
### 2. 读取对应模板
|
||||
在创建计划文档前，必须读取对应的模板内容，并严格按照模板的骨架进行填充：
|
||||
* **实现计划模板**：`docs/plan/implementation-plan-template.md`
|
||||
* **接手计划模板**：`docs/plan/handover-plan-template.md`
|
||||
|
||||
### 3. 落库与命名规范
|
||||
在 `docs/plan/` 目录下创建新的 Markdown 文件进行保存：
|
||||
* **实现计划**命名格式：`docs/plan/YYYYMMDD-[feature-name].md` (例如：`20260605-uptime-kuma-sync.md`)
|
||||
* **接手计划**命名格式：`docs/plan/handover-[task-name].md` (例如：`handover-waf-ip-group.md`)
|
||||
|
||||
### 4. 隔离约束 (极其重要)
|
||||
`docs/plan/` 目录下的文档**仅限内部开发和 AI 代理同步使用**。
|
||||
* **绝对禁止**将新创建的 plan 文档加入到项目的官方导航配置（如 `docs/config.ts` 的 `nav` 或 `sidebar` 导航条中）。
|
||||
* **绝对禁止**通过任何方式将其暴露给文档渲染框架（如 VitePress）对外渲染。
|
||||
|
||||
## 后续动作
|
||||
落库完成后，向用户报告计划已生成在 `docs/plan/` 目录下，并列出文档的核心要点或待决策项（如有），等待用户 Review 或批准后即可推进下一步。
|
||||
@@ -28,16 +28,14 @@ description: "Wavelet 项目专用：根据自上一个正式版本 Tag 以来
|
||||
|
||||
1. 合并重复或相近提交。
|
||||
2. 删除无意义提交，例如格式化、临时调试、无关重构。
|
||||
3. 将内部实现描述改写为用户可理解的变更。
|
||||
4. 每条使用完整中文句子。
|
||||
5. 尽量说明“修复/优化了什么”以及“带来的效果”。
|
||||
6. 不要编造 commit log 中没有的信息。
|
||||
7. 不要加入 token、密钥、私有地址等敏感信息。
|
||||
8. 如果某个分类没有内容，可以省略。
|
||||
3. 将内部实现描述改写为用户可理解的变更, 说明“修复/优化了什么”以及“带来的效果”。
|
||||
4. 不要写技术细节：只描述用户可感知的行为与效果，禁止内部实现描述，例如字段名/表名/SQL（`node_id = ''`）、框架或库名称（shadcn、GORM、OpenResty）、配置或协议细节（RFC3339、ClickHouse/PostgreSQL 差异）、代码机制（`proxy_intercept_errors`、Lua 过滤器、雪花 ID）。数据库名称仅在说明受影响用户范围时使用（如「PostgreSQL 日志库下无数据」）。
|
||||
5. 如果某个分类没有内容，则省略。
|
||||
|
||||
固定使用以下分类：
|
||||
|
||||
```text
|
||||
### ✨ 新功能
|
||||
### 🛠 修复
|
||||
### ⚡️ 优化与改进
|
||||
### 💄 其他/体验
|
||||
@@ -45,19 +43,29 @@ description: "Wavelet 项目专用：根据自上一个正式版本 Tag 以来
|
||||
|
||||
分类规则：
|
||||
|
||||
- 新功能、新能力、新配置、新任务：放入 ### ✨ 新功能
|
||||
- Bug、异常行为、错误逻辑：放入 ### 🛠 修复
|
||||
- 性能、稳定性、接口、架构、兼容性：放入 ### ⚡️ 优化与改进
|
||||
- 日志、文案、UI、文档、开发体验：放入 ### 💄 其他/体验
|
||||
|
||||
「修复/优化」与「新增」的判定（关键）：
|
||||
|
||||
- **判定标准是“该功能在上一正式版本中是否已存在”**：
|
||||
- 已存在 → 本次对其 bug 的修正可计入「🛠 修复」，对其行为/性能的改进可计入「⚡️ 优化与改进」；
|
||||
- 不存在（本版本新增）→ 该功能的一切内容——包括开发过程中修的 bug、做的性能优化、补的索引——都只属于新功能开发的一部分，不应该在发布说明中提及。
|
||||
- 禁止把新功能的开发期修复/优化写进「修复」或「优化」：新功能此前版本没有，谈不上“修复/优化了旧行为”。
|
||||
|
||||
示例:
|
||||
|
||||
```
|
||||
chore(release): v3.3.0
|
||||
|
||||
### ✨ 新功能
|
||||
- 新增笔记库快照备份功能，支持定时备份与手动一键恢复（仅说明新增的功能, 禁止提及新功能开发时期的优化修复等内容）。
|
||||
|
||||
### 🛠 修复
|
||||
- 修复了通过 MCP 接口操作时笔记库范围限制未正确生效的问题。
|
||||
- 修复了 MCP 接口返回数据格式不一致的问题。
|
||||
- 修复了 WebSocket 客户端异常断开后僵尸连接未及时清理的问题。
|
||||
- 修复首页「来源分布」卡片在 PostgreSQL/SQLite 日志库下无数据的问题。
|
||||
- 修复源站错误页「仅针对 GET 请求」未真正透传非 GET 响应的问题：POST/PUT 等非 GET 请求现可完整看到源站原始报错内容。
|
||||
|
||||
### ⚡️ 优化与改进
|
||||
- 优化了 WebGUI 登录机制，引入设备令牌自动轮转，减少因 IP 变化产生的冗余令牌。
|
||||
|
||||
@@ -1,19 +0,0 @@
|
||||
root = true
|
||||
|
||||
[*]
|
||||
indent_style = space
|
||||
indent_size = 4
|
||||
charset = utf-8
|
||||
end_of_line = lf
|
||||
trim_trailing_whitespace = true
|
||||
insert_final_newline = true
|
||||
|
||||
[*.{json,yml,yaml}]
|
||||
indent_size = 2
|
||||
|
||||
[*.md]
|
||||
insert_final_newline = false
|
||||
trim_trailing_whitespace = false
|
||||
|
||||
[*.{js,ts,css,html,jsx,tsx,vue}]
|
||||
indent_size = 2
|
||||
+1
-1
@@ -56,7 +56,7 @@ REDIS_MAINT_NOTIFICATIONS=false
|
||||
|
||||
# ─── ClickHouse（必需）────────────────────────────────────────────────────────
|
||||
# CLICKHOUSE_HOST 设置后会自动启用；测试环境可显式 CLICKHOUSE_ENABLED=true 做 live 联调
|
||||
CLICKHOUSE_ENABLED=true
|
||||
CLICKHOUSE_ENABLED=false
|
||||
# compose 内：clickhouse:9000；本机连映射端口：127.0.0.1:9000
|
||||
CLICKHOUSE_HOST=clickhouse:9000
|
||||
CLICKHOUSE_USERNAME=default
|
||||
|
||||
@@ -298,9 +298,7 @@ jobs:
|
||||
with:
|
||||
go-version-file: go.mod
|
||||
|
||||
- name: Fetch embedded GeoIP database
|
||||
run: bash scripts/fetch-agent-geoip-mmdb.sh
|
||||
|
||||
# GeoIP MMDB is not embedded; Docker images COPY mmdb files, bare binaries seed via download on first start.
|
||||
- name: Build Agent
|
||||
env:
|
||||
CGO_ENABLED: 0
|
||||
|
||||
+2
-2
@@ -77,8 +77,8 @@ profile.cov
|
||||
.grok
|
||||
/.gomodcache/
|
||||
*.mmdb
|
||||
!internal/apps/agent/geoipdata/GeoLite2-Country.mmdb
|
||||
!internal/apps/agent/geoipdata/GeoLite2-City.mmdb
|
||||
# Server control-plane MaxMind Country seed (Country only; Agent does not embed)
|
||||
!internal/apps/openflare/geoip/data/GeoLite2-Country.mmdb
|
||||
|
||||
/.superpowers/
|
||||
/.worktrees/
|
||||
|
||||
@@ -1,372 +1,228 @@
|
||||
# AGENTS.md
|
||||
|
||||
本文件是 OpenFlare 的 AI 接手入口，不承载详细设计、规范和计划。接手项目时，请根据以下分层文档指引进行阅读与开发：
|
||||
Behavioral guidelines to reduce common LLM coding mistakes. Merge with project-specific instructions as needed.
|
||||
|
||||
### 1. 开发指导规范 (AI & Developer Guidelines)
|
||||
**Tradeoff:** These guidelines bias toward caution over speed. For trivial tasks, use judgment.
|
||||
|
||||
* **必须阅读**：
|
||||
* **[docs/plan/index.md](./docs/plan/index.md)**：查看正在进行的开发实现计划（Implementation Plan）与 AI 代理交接文档（Handover），接手项目时优先检查。
|
||||
## 1. Think Before Coding
|
||||
|
||||
### 2. 系统设计与架构 (Design Docs)
|
||||
**Don't assume. Don't hide confusion. Surface tradeoffs.**
|
||||
|
||||
* **[docs/design/index.md](./docs/design/index.md)**：理解产品范围、系统边界、核心对象及长期约束，以及[仓库结构](./docs/design/index.md#仓库结构)。
|
||||
* **[docs/design/architecture.md](./docs/design/architecture.md)**：理解 Server、Agent、OpenResty 与前端的职责边界与网络拓扑。
|
||||
* **[docs/design/agent-design.md](./docs/design/agent-design.md)**：理解 Agent 设计原则、与 Server 交互时序、OpenResty 管控与配置发布回滚模型。
|
||||
Before implementing:
|
||||
- State your assumptions explicitly. If uncertain, ask.
|
||||
- If multiple interpretations exist, present them - don't pick silently.
|
||||
- If a simpler approach exists, say so. Push back when warranted.
|
||||
- If something is unclear, stop. Name what's confusing. Ask.
|
||||
|
||||
## 2. Simplicity First
|
||||
|
||||
**Minimum code that solves the problem. Nothing speculative.**
|
||||
|
||||
- No features beyond what was asked.
|
||||
- No abstractions for single-use code.
|
||||
- No "flexibility" or "configurability" that wasn't requested.
|
||||
- No error handling for impossible scenarios.
|
||||
- If you write 200 lines and it could be 50, rewrite it.
|
||||
|
||||
Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify.
|
||||
|
||||
## 3. Surgical Changes
|
||||
|
||||
**Touch only what you must. Clean up only your own mess.**
|
||||
|
||||
When editing existing code:
|
||||
- Don't "improve" adjacent code, comments, or formatting.
|
||||
- Don't refactor things that aren't broken.
|
||||
- Match existing style, even if you'd do it differently.
|
||||
- If you notice unrelated dead code, mention it - don't delete it.
|
||||
|
||||
When your changes create orphans:
|
||||
- Remove imports/variables/functions that YOUR changes made unused.
|
||||
- Don't remove pre-existing dead code unless asked.
|
||||
|
||||
The test: Every changed line should trace directly to the user's request.
|
||||
|
||||
## 4. Goal-Driven Execution
|
||||
|
||||
**Define success criteria. Loop until verified.**
|
||||
|
||||
Transform tasks into verifiable goals:
|
||||
- "Add validation" → "Write tests for invalid inputs, then make them pass"
|
||||
- "Fix the bug" → "Write a test that reproduces it, then make it pass"
|
||||
- "Refactor X" → "Ensure tests pass before and after"
|
||||
|
||||
For multi-step tasks, state a brief plan:
|
||||
```
|
||||
1. [Step] → verify: [check]
|
||||
2. [Step] → verify: [check]
|
||||
3. [Step] → verify: [check]
|
||||
```
|
||||
|
||||
Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification.
|
||||
|
||||
---
|
||||
|
||||
## Git 提交规范指南
|
||||
**These guidelines are working if:** fewer unnecessary changes in diffs, fewer rewrites due to overcomplication, and clarifying questions come before implementation rather than after mistakes.
|
||||
|
||||
### 提交信息基本格式
|
||||
|
||||
每次提交更改时，应当使用以下提交格式:
|
||||
|
||||
```text
|
||||
<type>(<scope>): <subject>
|
||||
|
||||
<body>
|
||||
```
|
||||
|
||||
* **Type**: 提交类型（例如 `feat`, `fix`, `refactor`, `perf`, `docs`, `chore` 等）。
|
||||
* **Scope** (可选): 影响的范围（例如 `api`, `frontend`, `auth`, `mcp` 等）。
|
||||
* **Subject**: 简短的一句话描述变更。
|
||||
* **Body** (可选): 详细的说明，多行叙述。
|
||||
|
||||
## 务必阅读匹配的 Skill
|
||||
## Skills（匹配任务时必读）
|
||||
|
||||
| Skill | 何时使用 |
|
||||
| :--- | :--- |
|
||||
| `new-api` | 添加或修改自定义业务 API、Handler、服务层逻辑、自定义路由注册 |
|
||||
| `new-async-task` | 添加或修改 Asynq 任务、定时任务、TaskHandler、任务元数据 |
|
||||
| `new-setting` | 添加或修改系统/业务/公开设置、`/admin/system` 参数或 `/admin/settings` 图形化设置 |
|
||||
| `database-migration` | 数据库表结构变更、goose SQL 迁移（PG/SQLite/ClickHouse）、seed 数据 |
|
||||
| `clickhouse-batchwriter` | ClickHouse 批量写入、`internal/infra/persistence/batchwriter` 接入、分析表异步 flush、背压与写入路径改造 |
|
||||
| `file-upload` | 业务上传文件、Worker 程序化摄取、`upload.Ingest` 策略选型、文件访问与 `w_uploads` / 统计排查 |
|
||||
| `cache-framework` | 新增或修改业务缓存（RAM/Redis/DB 三层读路径）、缓存失效、多节点 pub/sub 同步、评估高频读是否应接入缓存 |
|
||||
| `push-notification` | 系统通知推送事件、统一触发器投递、带消息推送的业务功能 |
|
||||
| `release-guide` | 根据自上一正式版本 Tag 以来的提交整理 Version Bump 提交信息以触发双语 Release |
|
||||
| `shadcn` | 添加、修改或组合 shadcn/ui 组件 |
|
||||
| `new-api` | 业务 API、Handler、服务层、路由注册 |
|
||||
| `new-async-task` | Asynq 任务、定时任务、TaskHandler、任务元数据 |
|
||||
| `new-setting` | 系统/业务/公开设置、`/admin/system`、`/admin/settings` |
|
||||
| `database-migration` | 表结构、goose 迁移（PG/SQLite/ClickHouse）、seed |
|
||||
| `clickhouse-batchwriter` | CH 批量写入、batchwriter、分析表 flush/背压 |
|
||||
| `file-upload` | 上传/摄取、`upload.Ingest`、文件访问、`w_uploads` |
|
||||
| `cache-framework` | 业务缓存（RAM/Redis/DB）、失效、多节点同步 |
|
||||
| `push-notification` | 通知推送事件、统一触发器、带推送的业务 |
|
||||
| `release-guide` | Version Bump 提交信息（触发双语 Release） |
|
||||
| `shadcn` | 添加/修改/组合 shadcn/ui 组件 |
|
||||
|
||||
## 硬性约束
|
||||
|
||||
## 严格遵循事项 (Guardrails)
|
||||
- 禁止删除 `frontend/node_modules`。
|
||||
- `pkg/util/` 保持纯净：禁止导入 Gin、GORM、sessions 等 HTTP/Web/DB 框架（会话选项在 `internal/apps/oauth/session.go`）。
|
||||
- 测试临时目录只用 `t.TempDir()`，禁止硬编码相对路径写源码树。
|
||||
- HTTP 路由仅在 `internal/router/router.go` 注册；`Serve()` 只挂路由与中间件，禁止进程级初始化（如 `SyncEvents`、`InitLogWriter`）。
|
||||
- API 变更后：`make swagger`；开发完成：`make code-check`；提交前：`make format`。
|
||||
- 缓存/文件管理复用平台实现，业务包禁止自建缓存目录或旁路存储后端。
|
||||
- 文件摄取走 `upload.Ingest`（`PolicyCreate` / `PolicyDedupNewRecord` / `PolicyResolveExisting`）；删除走 `upload.Remove` / `upload.RemoveOwned`。禁止业务直接 `repository.CreateUpload` / `SoftDeleteUpload` 或 `db.Create(&model.Upload{})`。
|
||||
- **分层**：`apps → repository → model`，`repository → infra/persistence`；禁止 `model → repository`。
|
||||
- `model`：实体、表名、配置 key、查询 DTO、无 IO 规则。禁止 `db.DB` / Redis / CH；禁止 `import repository`。GORM hook 仅可 mutate 自身字段，禁止在 hook 内再查 DB/缓存。
|
||||
- `repository`：唯一持久化入口。apps/logics 禁止为业务 CRUD 直调 `db.DB`（管理端 SQL 控制台、infra 内部等例外保留）。禁止新增 `model.Get/List/Create/...` 类数据访问 API。
|
||||
- 跨模块集成（任务 Handler、推送事件、域监听、完成钩子）禁止 `init()` 注册；经 `internal/platform/bootstrap` 在 `internal/cmd` 入口显式装配。
|
||||
- 核心业务（如 `oauth`、`user`）禁止直接 import push/custom_events；经 `internal/listener` 发域事件，push 在 bootstrap 订阅。
|
||||
- 依赖任务/推送注册的测试须显式 `bootstrap.RegisterTasks()` / `RegisterPushDomainEvents()` 等，不依赖 `init()`。
|
||||
- API 错误必须 `response.Abort*` + `ErrorHandlerMiddleware`；禁止 Handler 直接 `c.JSON(..., response.Err(...))` 或用 HTTP 200 表示失败。
|
||||
|
||||
- 切勿删除 `frontend/node_modules`
|
||||
- 保持 `pkg/util/` 绝对纯净且不引入任何框架。禁止从 `pkg/util/` 及其子包中导入 Gin、GORM、sessions 等 HTTP/Web/数据库相关框架包（例如，Web 会话选项已收敛至 `internal/apps/oauth/session.go`）。
|
||||
- 编写测试用例时，禁止使用硬编码的相对路径（如 `"uploads/test_cache"`）在源码目录下创建临时测试目录，必须统一使用 Go 内置的 `t.TempDir()` 以避免污染源码目录。
|
||||
- 所有 HTTP 路由仅在 `internal/router/router.go` 中注册。
|
||||
- 当 API Handler 发生变化时，更新 Swagger 文档（运行 `make swagger`）。
|
||||
- 在完成代码开发后必须运行 `make code-check`, 并修复报错。
|
||||
- 在完成代码开发后或者 git 提交前必须运行 `make format` 格式化代码。
|
||||
- 需要缓存或文件管理能力时，必须复用现有平台实现，禁止在业务包中自行创建缓存目录、直接管理缓存文件或重复封装存储后端。
|
||||
- 文件摄取必须通过 `upload.Ingest`（`upload.PolicyCreate` / `PolicyDedupNewRecord` / `PolicyResolveExisting`）；删除必须通过 `upload.Remove` 或 `upload.RemoveOwned`。禁止业务模块直接调用 `repository.CreateUpload` / `repository.SoftDeleteUpload`，禁止 `db.Create(&model.Upload{})` 旁路写 `w_uploads`。
|
||||
- **`internal/model` 与 `internal/repository` 分层（硬规则）**：
|
||||
- `internal/model/`：仅 GORM 实体、表名、配置 key、查询 DTO、无 IO 领域规则（如密码哈希校验、字段规范化）。**禁止**在 model 中调用 `db.DB` / Redis / ClickHouse，**禁止** `import internal/repository`。
|
||||
- 实体上允许仅 mutate 自身字段的 GORM hook（如 `AfterFind(*gorm.DB)`），**禁止**在 hook 内再发起 DB/缓存查询。
|
||||
- `internal/repository/`：唯一持久化入口（CRUD、事务、缓存、分析查询）。apps / logics / task 框架通过 repository 访问数据，**禁止**在 Handler 内直接写复杂 SQL。
|
||||
- apps 不得为业务 CRUD 直接调用 `db.DB`；必须走 repository（管理端 SQL 控制台、infra 内部实现等例外可保留）。
|
||||
- 依赖方向只能是 `apps → repository → model` 与 `repository → infra/persistence`；**禁止** `model → repository`。
|
||||
- 新增代码不得再增加 `model.Get/List/Create/Update/Delete*(ctx…)` 类数据访问 API；存量迁移按域收敛至 repository。
|
||||
- 禁止在 `init()` 中注册跨模块集成（任务 Handler、推送内置事件、域事件监听器、任务完成钩子）。统一通过 `internal/platform/bootstrap` 在 `internal/cmd` 入口显式装配。
|
||||
- `internal/router/router.go` 的 `Serve()` 仅负责 HTTP 路由与中间件，禁止在其中执行 `SyncEvents`、`InitLogWriter` 等进程级运行时初始化。
|
||||
- 核心业务模块（如 `oauth`、`user`）禁止直接 `import` `internal/apps/admin/push` 或 `custom_events` 触发通知；应通过 `internal/listener` 发射域事件，由 push 模块在 bootstrap 阶段订阅。
|
||||
- 编写依赖任务注册或推送事件同步的测试时，必须在测试 setup 中显式调用 `bootstrap.RegisterTasks()`、`bootstrap.RegisterPushDomainEvents()` 等，不得依赖 `init()` 副作用。
|
||||
- API 错误响应必须通过 `response.Abort*` 中断请求，由 `ErrorHandlerMiddleware` 统一写出 JSON；禁止 `c.JSON(http.StatusOK, response.Err(...))` 及 Handler 直接 `c.JSON(status, response.Err(...))`。
|
||||
1. **设计先行**：
|
||||
* 开发新功能或重要特性时，必须在 `docs/design/` 下创建/更新对应的设计文档，理清架构与核心决策。
|
||||
* 新增的设计文档应同步更新至 `docs/design/architecture.md` 及在 `docs/config.ts` 中注册侧边栏路由。
|
||||
* 若实现内容超出产品边界，必须先修改设计文档，再编码实现。
|
||||
3. **开发计划与交接**：
|
||||
* 正在进行的开发计划或 AI 接手交接发生变化时，在 `docs/plan/` 下更新对应的开发计划或接手文档，并使用相应模板初始化。
|
||||
4. **文档与变更日志**：
|
||||
* 当相关内容发生变化时，同步更新对应的**中文文档**（不要同步英文文档）。
|
||||
* 代码或配置变更完成后，必须在 [`docs/changelog/index.md`](./docs/changelog/index.md) 的 `[Unreleased]` 区块补充对应变更条目。
|
||||
* **纯文档变更（如 `docs/` 下的 Markdown 文档、README 等）不需要写入 changelog。**
|
||||
* 更新 changelog 时遵循以下书写规则：
|
||||
1. 合并重复或相近的变更，不按提交逐条罗列。
|
||||
2. 不记录格式化、临时调试、无关重构等对用户无意义的变更。
|
||||
3. 使用用户可理解的表述，不描述内部实现细节。
|
||||
4. 每条均使用完整中文句子，并尽量说明修复或优化的内容及其带来的效果。
|
||||
5. 仅基于实际变更撰写，不编造提交或代码中不存在的信息。
|
||||
6. 不记录 Token、密钥、私有地址等敏感信息；没有内容的分类可以省略。
|
||||
### 文档与 Changelog
|
||||
|
||||
## 项目介绍
|
||||
- 内容变更同步**中文文档**（不同步英文）。
|
||||
- 代码/配置变更写入 [`docs/changelog/index.md`](./docs/changelog/index.md) 的 `[Unreleased]`；纯文档变更不写 changelog。
|
||||
- Changelog：合并相近项；不记格式化/调试/无关重构；用户可读完整中文句；说明效果；不编造；不写密钥等敏感信息；空分类可省略。
|
||||
|
||||
### 技术栈
|
||||
## 技术栈
|
||||
|
||||
- 后端：Go 1.25+、Gin、GORM、PostgreSQL、可选 ClickHouse、Redis、Asynq、Cobra、Viper、Swaggo、OpenTelemetry、Zap、AWS SDK v2、Snowflake IDs。
|
||||
- 前端：Next.js App Router、TypeScript、Tailwind CSS、pnpm、shadcn/ui。
|
||||
- **后端**：Go 1.25+、Gin、GORM、PostgreSQL、可选 ClickHouse、Redis、Asynq、Cobra、Viper、Swaggo、OTel、Zap、AWS SDK v2、Snowflake IDs
|
||||
- **前端**：Next.js App Router、TypeScript、Tailwind、pnpm、shadcn/ui
|
||||
|
||||
### 目录结构与平台能力
|
||||
## Git
|
||||
|
||||
顶层目录：
|
||||
Conventional Commits：`<type>(<scope>): <subject>`（例：`feat(auth): support email login`）。
|
||||
|
||||
- `main.go`：程序入口，委派给 `internal/cmd`。
|
||||
- `config.example.yaml`：已提交的配置模板。在添加配置字段时保持更新。
|
||||
- `config.yaml`：本地运行时的配置文件。不要将其作为已提交的源码提交。
|
||||
- `docker/`：集成的、仅前端的和仅后端的 Dockerfile。
|
||||
- `docs/`：自动生成的 Swagger 文档。请勿手动编辑生成的文件。
|
||||
- `frontend/`：Next.js 应用。
|
||||
- `internal/`：私有 Go 后端代码。
|
||||
- `pkg/`：公共 Go 库/工具包（留作扩展或存放不依赖特定业务的通用代码）。
|
||||
- `scripts/`：本地和 CI 辅助脚本。
|
||||
- `support-files/`：部署 and 数据库辅助文件。
|
||||
- `bin/`：本地编译生成的二进制可执行文件。
|
||||
- `data/`：本地运行时数据文件目录（如 PostgreSQL、Redis 数据等）。
|
||||
- `uploads/`：本地文件上传存储目录。
|
||||
---
|
||||
|
||||
后端目录：
|
||||
## 后端
|
||||
|
||||
- `internal/cmd/`：用于 API、worker、scheduler、root init 的 Cobra 命令。进程启动时在此调用 `bootstrap.Register*` 与 `bootstrap.Init`，再启动 router / worker / scheduler。
|
||||
- `internal/platform/bootstrap/`：应用装配根（composition root）。集中注册任务 Handler、推送域事件订阅、任务完成监听器，并执行 `SyncEvents`、ClickHouse 访问日志写入等进程级初始化；所有注册函数使用 `sync.Once` 保证幂等。
|
||||
- `internal/infra/config/`：Viper 加载和配置结构体。运行时代码应使用 `config.Config.<Section>.<Field>`。
|
||||
- `internal/router/`：唯一的 HTTP 路由注册点。
|
||||
- `internal/apps/`：按功能（Feature-based）组织的 HTTP Handler、中间件、内部服务与模块逻辑。移除全局 service 层，模块内部业务逻辑（如验证码业务逻辑管理器 `internal/apps/cap/manager.go`）均收敛于各自模块中；管理端模块位于 `internal/apps/admin/`。
|
||||
- `internal/apps/upload/`：上传记录、文件访问控制、本地/S3 文件响应、下载及图片 WebP 压缩。业务应复用 `upload.Ingest` / `upload.Remove` 与 `GET /f/:id` 文件服务，不直接操作底层 storage 或旁路写 `w_uploads`。
|
||||
- `internal/model/`：GORM 实体、表映射、配置 key、查询 DTO 与无 IO 领域规则；不含数据库访问。
|
||||
- `internal/repository/`：数据访问层（平台与业务域 CRUD、缓存、ClickHouse 分析读写）；唯一持久化入口。
|
||||
- `internal/infra/persistence/`：PostgreSQL、Redis、ClickHouse、GORM 日志、ID 生成和 goose SQL 迁移的布线。
|
||||
- `internal/infra/diskcache/`：平台级磁盘字节缓存，通过 `diskcache.GetGlobalCache()` 提供 TTL、最大空间限制、LRU 淘汰、清空、状态统计和配置热更新。写入时使用 `DefaultExpiration`（全局默认 TTL）、正数 `time.Duration`（业务 TTL）或 `NoExpiration`（无 TTL，仍受空间限制和 LRU 淘汰）。
|
||||
- `internal/infra/objectstore/`：S3 兼容对象存储适配，提供对象上传、读取、删除、CDN/代理读取及远端对象本地缓存。
|
||||
- `internal/infra/task/`：Asynq 任务框架；参见 `new-async-task` 了解变更。
|
||||
- `internal/shared/`：共享的通用模型及响应（如 `internal/shared/response`）、绑定（bind）、常量以及通用错误。
|
||||
- `pkg/util/`：纯底层无副作用的系统工具（Crypto/Password/UUID、格式化、网络、版本比较等）。
|
||||
- `internal/listener/`：域事件分发层。核心域（auth、user 等）在此定义并发射事件（如 `EmitAdminLoggedIn`）；运维模块（push、webhook 等）在 bootstrap 阶段订阅，实现跨模块解耦。
|
||||
- `internal/otel_trace/`：链路追踪（tracing）助手。
|
||||
- `internal/testhelper/`：后端测试共享辅助能力。
|
||||
- `internal/buildinfo/`：暴露在发布/构建工作流中注入的元数据（如版本号、编译时间等）。
|
||||
### 命名
|
||||
|
||||
公共底层包 (`pkg/`)：
|
||||
- `pkg/cache/disk/`：纯底层的通用本地磁盘缓存引擎。
|
||||
- `pkg/cap/`：底层的通用验证码验证和生成库。
|
||||
- `pkg/httppool/`：管理全局共享且经过优化的 HTTP 传输客户端及连接池，集成 OTel 链路追踪。
|
||||
- `pkg/logger/`：Zap 和 OTel 日志助手。
|
||||
- `pkg/push/`：推送渠道客户端集成（Lark/Telegram/Email）。
|
||||
- `pkg/mail/`：邮件发送客户端。
|
||||
- `pkg/trace/`：OpenTelemetry 链路追踪配置。
|
||||
| 类别 | 规则 | 例 |
|
||||
|------|------|-----|
|
||||
| 包/文件 | 小写蛇形 | `auth_source`、`postgres_logger.go` |
|
||||
| 导出/未导出标识符 | PascalCase / camelCase | — |
|
||||
| 请求/响应结构体 | camelCase + 后缀 | `listUsersRequest` |
|
||||
| 错误文案常量 | camelCase 字符串 `const`（非包级 `error`） | `errBindParamsFailed` |
|
||||
| YAML 键 | 小写蛇形 | — |
|
||||
|
||||
前端目录：
|
||||
### Handler
|
||||
|
||||
- `frontend/app/`：App Router 页面、路由组、根布局、全局配置。
|
||||
- `frontend/components/ui/`：shadcn/ui 基础组件。
|
||||
- `frontend/components/common/`：跨页面的业务组件。
|
||||
- `frontend/components/layout/`：Header、Sidebar、Footer 等应用布局组件。
|
||||
- `frontend/components/auth/`、`home/`、`animate-ui/`、`providers/`：特定作用域的 UI 组件。
|
||||
- `frontend/lib/services/`：基于 `BaseService` 的类型化 API 服务，按业务域拆分并由 `services` 对象统一导出。
|
||||
- `frontend/contexts/`、`hooks/`、`lib/`、`types/`、`public/`：共享状态、Hook、客户端与实用工具、TypeScript 类型、静态资产。
|
||||
- `frontend/scripts/`：前端构建和维护脚本。
|
||||
- `frontend/.next/`、`frontend/out/`、`frontend/node_modules/`：本地生成或安装的产物，不作为业务源码编辑。
|
||||
- 命名：动词 + 名词（`ListUsers`）；绑定用 `ShouldBindQuery` / `ShouldBindJSON`。
|
||||
- 每个 HTTP API 需完整 Swagger 注释；API 变更后 `make swagger`。
|
||||
- Handler：绑定 → 调 logic → 映射为 `Abort*` 或 `response.OK`。
|
||||
- `logics.go`：接受 `context.Context`，返回结果/error；**禁止**依赖 `*gin.Context`、调用 `Abort*` / `c.JSON`。参考 `internal/apps/user/logics.go`。
|
||||
|
||||
### API 响应
|
||||
|
||||
## 开发要求
|
||||
信封：`{ "error_msg": "", "data": ... }`。成功 `error_msg` 空、`data` 为载荷；失败 `data` 为 `null`。分页：`data: { total, results }`。
|
||||
|
||||
### 后端规则
|
||||
|
||||
命名规范：
|
||||
|
||||
- Go 包和文件使用小写蛇形命名（lowercase snake case）：如 `auth_source`、`postgres_logger.go`。
|
||||
- 导出的 Go 标识符使用 PascalCase；未导出的标识符使用 camelCase。
|
||||
- 请求/响应结构体使用 camelCase 并带有后缀，例如 `listUsersRequest` 和 `listUsersResponse`。
|
||||
- 错误消息常量是 camelCase 字符串 `const`值，而不是包级别的 `error` 值。
|
||||
- YAML 配置键使用小写蛇形命名（lowercase snake case）。
|
||||
|
||||
Handler 规范：
|
||||
|
||||
- Handler 命名为 动词 + 名词，例如 `ListUsers`。
|
||||
- 使用 `ShouldBindQuery` 或 `ShouldBindJSON` 进行绑定。
|
||||
- 每个 HTTP API 都需要有完整的 Swagger 注释；在 API 变更后运行 `make swagger`。
|
||||
|
||||
#### API 响应信封（统一格式）
|
||||
|
||||
所有 JSON API 响应的外层结构**必须**为：
|
||||
|
||||
```json
|
||||
{ "error_msg": "", "data": ... }
|
||||
```
|
||||
|
||||
- 成功时：`error_msg` 为空字符串，`data` 承载业务载荷。
|
||||
- 失败时：`data` 为 `null`，`error_msg` 为用户可见的错误说明。
|
||||
- 分页响应在 `data` 下使用 `{ "total": 0, "results": [] }`。
|
||||
|
||||
#### 成功响应（唯一写法）
|
||||
|
||||
成功时**始终**使用 HTTP `200`，由 Handler 直接写出 JSON：
|
||||
**成功**（始终 HTTP 200）：
|
||||
|
||||
```go
|
||||
import (
|
||||
"net/http"
|
||||
"github.com/Rain-kl/Wavelet/internal/shared/response"
|
||||
"github.com/gin-gonic/gin"
|
||||
)
|
||||
|
||||
// 有数据
|
||||
c.JSON(http.StatusOK, response.OK(data))
|
||||
|
||||
// 无数据（data 为 null）
|
||||
c.JSON(http.StatusOK, response.OKNil())
|
||||
```
|
||||
|
||||
#### 失败响应（中断请求，禁止直接写错误 JSON）
|
||||
**失败**：仅用 `response.Abort*`（挂 `c.Errors` 并 `Abort`，由 `ErrorHandlerMiddleware` 统一写出并记 OTel）,阅读/internal/shared/response/abort.go使用已有函数
|
||||
|
||||
失败时**禁止**在 Handler / 中间件中直接调用 `c.JSON(..., response.Err(msg))`，也**禁止**用 HTTP `200` 携带非空 `error_msg` 表示失败。
|
||||
中间件同规则（`oauth.LoginRequired` → Unauthorized；`admin.LoginAdminRequired` → NotFound；`cap.VerifyMiddleware` → Unauthorized）。
|
||||
|
||||
统一通过 `internal/shared/response` 的 **Abort 系列函数**中断请求。这些函数会将 `*response.APIError` 挂载到 Gin 的 `c.Errors` 链并 `c.Abort()`；请求结束后由全局 `response.ErrorHandlerMiddleware()`（在 `internal/router/middlewares.go` 中注册）统一写出 JSON，并记录到 OpenTelemetry Trace/Jaeger。
|
||||
- 用户可见错误：模块内 `errs.go` 的 camelCase 字符串常量；禁止向客户端暴露驱动错误/堆栈。
|
||||
- `response.Err` 仅供中间件构造 JSON，业务禁止用于 `c.JSON`。
|
||||
|
||||
**推荐使用的便捷函数（优先于手写状态码）：**
|
||||
**禁止**：`c.JSON(200, response.Err(...))`；Handler 直接 `c.JSON(4xx/5xx, response.Err(...))`；手写 `gin.H` 错误体；在 `logics.go` 里 `Abort*`。
|
||||
|
||||
| 函数 | HTTP 状态码 | 典型场景 |
|
||||
|------|-------------|----------|
|
||||
| `response.AbortBadRequest(c, msg)` | 400 | 参数绑定失败、字段校验、业务规则拒绝（如密码错误、重复注册） |
|
||||
| `response.AbortUnauthorized(c, msg)` | 401 | 未登录、Session/Token 失效（`oauth.LoginRequired()`） |
|
||||
| `response.AbortForbidden(c, msg)` | 403 | 已登录但无权访问（如 Token 不允许访问的端点） |
|
||||
| `response.AbortNotFound(c, msg)` | 404 | 资源不存在；管理员中间件对非管理员隐藏端点时也使用此码 |
|
||||
| `response.AbortConflict(c, msg)` | 409 | 资源冲突（如唯一键重复） |
|
||||
| `response.AbortTooManyRequests(c, msg)` | 429 | 限流、频率限制 |
|
||||
| `response.AbortInternal(c, msg)` | 500 | 对用户返回通用提示；底层错误须先记录日志 |
|
||||
| `response.AbortWithError(c, code, msg)` | 自定义 | 上表未覆盖的状态码时使用 |
|
||||
Swagger：`@Success 200` 用具体类型或 `response.Any`；每个可能 Abort 状态声明 `@Failure`。
|
||||
|
||||
**标准 Handler 模板：**
|
||||
### 日志
|
||||
|
||||
```go
|
||||
func CreateWidget(c *gin.Context) {
|
||||
var req createWidgetRequest
|
||||
if err := c.ShouldBindJSON(&req); err != nil {
|
||||
response.AbortBadRequest(c, errBindParamsFailed)
|
||||
return
|
||||
}
|
||||
- 运行时错误（DB/Redis/第三方/IO）在 Handler 或 logic 边界用 `pkg/logger`（带 `ctx`）记录，再返回安全 Abort/业务错误。
|
||||
- 吞错、转通用响应、worker 忽略前必须先记日志。
|
||||
- 禁止 `_ = err` 静默丢弃重要错误；best-effort 可忽略时加简短注释。
|
||||
- 只在处理/抑制边界记一次，避免重复刷日志。
|
||||
|
||||
widget, err := createWidgetLogic(c.Request.Context(), req)
|
||||
if err != nil {
|
||||
// 底层错误已记录日志时，向用户返回安全文案
|
||||
response.AbortBadRequest(c, err.Error()) // 或按语义选用 AbortConflict / AbortInternal 等
|
||||
return
|
||||
}
|
||||
### 路由与装配
|
||||
|
||||
c.JSON(http.StatusOK, response.OK(widget))
|
||||
}
|
||||
```
|
||||
- `router.go` 只做高层分发，禁止直接挂业务 Handler。归属与开发步骤见 `new-api` skill。
|
||||
- 跨模块副作用：在 `bootstrap` 增 `Register*`，于对应 `internal/cmd/*.go` 调用（`RegisterAPI` / `RegisterWorker` / `RegisterAll`）。
|
||||
- API/`all` 模式：`bootstrap.Init` 须在 `RegisterPushDomainEvents()` **之后**调用，保证 `SyncEvents` 同步内置推送元数据。
|
||||
|
||||
**中间件**与 Handler 遵循同一规则。参考 `oauth.LoginRequired()` → `AbortUnauthorized`，`admin.LoginAdminRequired()` → `AbortNotFound`，`cap.VerifyMiddleware` → `AbortUnauthorized`。
|
||||
### 中间件
|
||||
|
||||
#### 错误消息定义
|
||||
- 全局：`gin.Recovery()`、`otelgin`、日志、session。
|
||||
- 登录组：`oauth.LoginRequired()`；管理组：`admin.LoginAdminRequired()`。
|
||||
|
||||
- 面向用户的错误文案定义为模块内 **camelCase 字符串常量**（放在 `errs.go`），例如 `errBindParamsFailed = "参数绑定失败"`。
|
||||
- Handler / 中间件向 Abort 函数传入这些常量或经校验的安全字符串；**禁止**将数据库驱动错误、堆栈信息等内部细节直接暴露给客户端。
|
||||
- `response.Err(msg)` 仅供 `ErrorHandlerMiddleware` 内部构造 JSON，**业务代码不得直接用于 `c.JSON`**。
|
||||
### 配置
|
||||
|
||||
#### `logics.go` 与 Handler 的分工
|
||||
- 运行时只读 `config.Config`，禁止 `os.Getenv()`。
|
||||
- 新增配置同步 `config.example.yaml` 与 `internal/infra/config/model.go`。
|
||||
|
||||
- `logics.go` 接受 `context.Context`，返回 `(result, error)` 或带状态的业务结果结构体（参考 `internal/apps/user/logics.go` 的 `LoginEmailVerificationResult`）。
|
||||
- `logics.go` **不得**依赖 `*gin.Context`，**不得**调用 `response.Abort*` 或 `c.JSON`。
|
||||
- Handler 负责：绑定参数 → 调用 logic → 将 logic 错误/状态映射为对应的 `Abort*` 或 `response.OK`。
|
||||
### 数据库
|
||||
|
||||
#### 日志与内部错误
|
||||
- 持久化只经 `repository`（或 analytics）；复杂查询不进 Handler；编排在 logics。
|
||||
- repository 内用 `db.DB(ctx)`（链路追踪）。
|
||||
- 迁移：`internal/infra/persistence/migrator/goose/` SQL；禁止 GORM AutoMigrate。
|
||||
- 不建物理外键，关系字段加显式索引。
|
||||
- 列默认值与 Go 零值（`nil`/`0`/`false`/`""`）一致。
|
||||
|
||||
- 数据库、Redis、第三方 API、文件 I/O 等**运行时错误**：在 Handler 或 logic 边界用 `pkg/logger` 记录（带 `ctx`），再向用户返回安全的 `AbortInternal` 或语义匹配的业务错误常量。
|
||||
- 任何关键错误在被吞掉、转换为通用响应，或由后台 worker 忽略之前，都必须通过 `pkg/logger` 打印日志。
|
||||
- 禁止用 `_ = ...` 静默丢弃重要错误。如果某个错误因为 best-effort 操作或确认无害而需要忽略，必须添加简短注释说明原因。
|
||||
- 避免重复刷日志：在真正处理或抑制错误的边界记录一次，然后 `Abort*` 或成功返回。
|
||||
---
|
||||
|
||||
#### 禁止写法（反模式）
|
||||
## 前端
|
||||
|
||||
```go
|
||||
// ❌ 禁止：HTTP 200 表示失败
|
||||
c.JSON(http.StatusOK, response.Err("密码错误"))
|
||||
- Next.js：以 `node_modules/next/dist/docs/` 为准（训练数据可能过时）。
|
||||
- 示例：`frontend/app/(main)/admin/demo`。
|
||||
|
||||
// ❌ 禁止：Handler 直接写错误 JSON，绕过 ErrorHandlerMiddleware 与 OTel 记录
|
||||
c.JSON(http.StatusBadRequest, response.Err("参数错误"))
|
||||
### 样式
|
||||
|
||||
// ❌ 禁止：gin.H 手写错误体
|
||||
c.AbortWithStatusJSON(http.StatusBadRequest, gin.H{"error_msg": "...", "data": nil})
|
||||
- shadcn 用 `variant` + CSS 变量；业务 `className` 不硬编码颜色/背景/阴影。
|
||||
- 变体不足时扩展组件 variant，不写一次性颜色。
|
||||
|
||||
// ❌ 禁止：logics.go 中中断 HTTP 请求
|
||||
func doSomething(c *gin.Context) { response.AbortBadRequest(c, "...") }
|
||||
```
|
||||
### 页面结构
|
||||
|
||||
#### Swagger 注释约定
|
||||
- 根容器全宽 `w-full`；禁止页面级 `max-w-*`（主布局负责宽度）。
|
||||
- 外层间距：`py-6` 或 `py-6 px-1`。
|
||||
- 标题行：`flex items-center gap-2`（有右侧操作则加 `justify-between`）。
|
||||
- 图标：Lucide 直接放标题容器，`size-5 text-primary`；禁止背景卡片/边框包裹。
|
||||
- 标题：仅 `h1 className="text-2xl font-semibold tracking-tight"`。
|
||||
- 多 Tab：各 Tab 独立文件；`page.tsx` 只管 Tabs 状态与触发器；禁止 `page.tsx` 仅转发同名空壳。
|
||||
- 单文件 > ~600 行或状态过重时拆局部 `components/`；跨页复用放 `frontend/components/common/`。标杆：`/admin/database`。
|
||||
|
||||
- `@Success 200` 的 `data` 使用具体类型或 `response.Any`。
|
||||
- 对每个可能返回的 Abort 状态码声明 `@Failure`，例如 `@Failure 400 {object} response.Any "参数错误"`、`@Failure 401 {object} response.Any "未登录"`。
|
||||
### 组件放置
|
||||
|
||||
路由与模块：
|
||||
| 类型 | 路径 |
|
||||
|------|------|
|
||||
| 跨页业务 | `frontend/components/common/` |
|
||||
| shadcn 原语 | `frontend/components/ui/` |
|
||||
| 路由专属 | 邻近 feature 目录 |
|
||||
|
||||
- 仅在 `internal/router/router.go` 中作为统一高层入口进行路由分发委派，不允许在 `router.go` 中直接挂载业务 Handler。
|
||||
- 关于所有的路由归属划分、接口开发隔离防线以及详细的注册和开发步骤，请直接阅读并严格遵循 [new-api](.agents/skills/new-api/SKILL.md) 技能。
|
||||
|
||||
应用装配与跨模块集成：
|
||||
|
||||
- 新增跨模块副作用（任务注册、推送订阅、后台监听器）时，在 `internal/platform/bootstrap/bootstrap.go` 增加 `Register*` 函数，并在对应 `internal/cmd/*.go` 入口调用；参考现有 `RegisterAPI` / `RegisterWorker` / `RegisterAll` 分工。
|
||||
- `bootstrap.Init` 必须在 `RegisterPushDomainEvents()` 之后调用（API/`all` 模式），以确保 `SyncEvents` 能同步内置推送事件元数据。
|
||||
- Handler 与业务逻辑分离：HTTP Handler 负责绑定与响应；可复用逻辑放入 `logics.go`（接受 `context.Context`，不依赖 `*gin.Context`），便于 Worker 与单元测试复用。参考 `internal/apps/user/logics.go`。
|
||||
|
||||
中间件：
|
||||
|
||||
- 全局中间件属于路由设置：`gin.Recovery()`、`otelgin.Middleware()`、日志中间件 and session 中间件。
|
||||
- 对于登录路由组，使用 `oauth.LoginRequired()`。
|
||||
- 对于管理路由组，使用 `admin.LoginAdminRequired()`。
|
||||
|
||||
配置管理：
|
||||
|
||||
- 运行时代码从 `config.Config` 中读取配置，绝对不要直接从 `os.Getenv()` 中读取。
|
||||
- 当添加配置时，同时更新 `config.example.yaml` and `internal/infra/config/model.go`。
|
||||
|
||||
数据库操作：
|
||||
|
||||
- **持久化只通过 `internal/repository`**（或 analytics 子包）。apps / logics 不要直接 `db.DB(ctx).Where...` 拼复杂查询；简单事务编排可在 logics 中调用多个 repository 方法。
|
||||
- repository 内管理员/业务查询应使用 `db.DB(ctx)` 以获得链路追踪感知的 DB 访问。
|
||||
- 不要在 Handler 中放置 SQL；复杂查询放 `internal/repository/`，业务编排放 `internal/apps/<module>/logics.go`（或 `service.go`）。
|
||||
- `internal/model` 只定义实体与无 IO 规则，不访问数据库。
|
||||
- 在 `internal/infra/persistence/migrator/goose/` 下使用 goose SQL 迁移；不要添加基于 GORM AutoMigrate 的 Schema 升级。
|
||||
- 不要创建物理数据库外键。改为关系字段添加显式索引。
|
||||
- 数据库默认值必须与 Go 模型零值（`nil`、`0`、`false`、`""`）匹配，以避免意外的插入。
|
||||
|
||||
### 前端规则
|
||||
|
||||
在进行任何 Next.js 工作之前，请在 `node_modules/next/dist/docs/` 中找到并阅读相关文档。您的训练数据已过时 —— 这些文档是唯一的真理来源。
|
||||
|
||||
请直接查看并参考项目提供的示例和 Demo 代码：[frontend/app/(main)/admin/demo](frontend/app/(main)/admin/demo)。
|
||||
|
||||
样式规范：
|
||||
|
||||
- shadcn/ui 基础组件应该使用它们的 `variant` 系统和全局 CSS 变量。当组件的变体（variant）应该拥有某种外观时，不要在业务 `className` 中硬编码颜色、背景或阴影。
|
||||
- 如果现有的变体不足以满足需求，请扩展 shadcn/ui 组件的变体，而不是硬编码一次性的颜色。
|
||||
|
||||
页面标题栏规范 (新人开发与重构必读)：
|
||||
|
||||
- **容器与对齐机制**：
|
||||
- 标题容器统一使用 `flex items-center gap-2`。如果右侧有操作按钮（如“新增”、“刷新”），请使用 `justify-between` 布局让操作区与标题双向分布。
|
||||
- 为了确保所有页面在进入/切换时，顶部的呼吸感和视觉高度完全一致，页面最外层容器**必须**统一使用 `py-6 px-1` 或 `py-6` 进行上边距对齐。
|
||||
- **图标标准**：图标作为视觉辅助点缀，**必须**直接嵌套在标题容器中，直接使用 Lucide 图标组件，样式大小限制为 `size-5 text-primary`。**严禁**为图标包裹任何背景小卡片、圆角边框或额外的修饰容器。
|
||||
- **标题文字标准**：标题文字使用且仅使用 `h1 className="text-2xl font-semibold tracking-tight"`。不要自行定义字号、字量（如使用 `font-bold`）或添加任何渐变色，保持整个系统的字形规范化。
|
||||
- **Tabs 模块化与文件拆分规范**：凡是带有多个 Tab 页切换的复杂页面，**禁止**将所有 Tab 的渲染逻辑堆积在同一个主文件内。每个 Tab 的具体渲染内容必须单独拆分为独立的 React 组件文件（如 `tabs/events-tab.tsx`）。主页面文件应该仅用于导入子组件、注册 Tabs 触发器以及管理 Tab 的切换激活状态。这有利于防止单文件过大（避免单文件行数超过 600 行限制），并大幅度提高代码的可读性与编译维护效率。
|
||||
- **扁平化结构与避免冗余中间件**：为了消除无意义的“中间代理文件”，所有作为路由物理入口的 Tabs 状态维护、骨架及外层布局代码，**必须**直接定义在 Next.js 的 `app/` 页面文件（即 `page.tsx`）中。禁止在 `page.tsx` 中仅写一个单纯的 `<AnotherComponent />` 转发，而在外部新建一个同名中转容器。
|
||||
- **复杂度驱动的组件拆分规范**：组件的拆分不应局限于“跨页面复用”。当一个路由页面的复杂度变高时（如渲染逻辑膨胀、存在大型嵌套弹窗或多层状态管理，如单文件代码行数超过 600 行），必须主动将其拆分为子组件以维持单文件的高可读性与低耦合度。拆分时遵循就近原则：特定于该路由且不复用的子组件应放置在最邻近该路由的特征目录（Feature Folder，如 `components/` 局部文件夹）中；只有真正具备跨页面复用价值的通用业务/基础 UI 组件才应存放在全局 `components/` 共享目录下。
|
||||
- **最佳实践标杆案例（数据管理 `/admin/database`）**：
|
||||
该页面由于整合了“运行状态概览”、“物理表网格浏览器”、“磁盘缓存管理”和“SQL 交互控台”多个复杂大区块，重构前单文件接近 1000 行。
|
||||
重构后，主页面 `page.tsx` 仅做高级页面骨架与排版排布，维护全局刷新机制与终端视图切换；而“数据表浏览器 (`table-browser.tsx`)”、“缓存管理 (`cache-manager.tsx`)”与“SQL 终端 (`sql-console.tsx`)”等独立高状态密度区块均被抽离为局部子组件，存放在 `frontend/app/(main)/admin/database/components/`。这保证了代码结构层次清晰、单文件小巧好维护。所有复杂页面的新开发和重构必须遵循此模式。
|
||||
|
||||
页面宽度：
|
||||
|
||||
- 页面根容器必须支持全宽。使用 `w-full`。
|
||||
- 不要硬编码页面级的最大宽度，如 `max-w-6xl` 或 `max-w-4xl`；主布局（main layout）拥有正常/全宽的限制。
|
||||
|
||||
组件放置：
|
||||
|
||||
- 跨页面的业务组件属于 `frontend/components/common/`。
|
||||
- shadcn/ui 原生组件（primitives）属于 `frontend/components/ui/`。
|
||||
- 特定于路由/页面的组件放在最邻近的特征（feature）目录中。
|
||||
|
||||
服务类（Services）：
|
||||
|
||||
- 前端 API 访问通过服务类和导出的 `services` 对象进行。
|
||||
- 新增服务结构如下：
|
||||
### Services
|
||||
|
||||
```text
|
||||
frontend/lib/services/<service-name>/
|
||||
frontend/lib/services/<name>/
|
||||
types.ts
|
||||
<service-name>.service.ts
|
||||
<name>.service.ts
|
||||
index.ts
|
||||
```
|
||||
|
||||
- 服务类继承 `BaseService`，定义 `basePath`，并暴露有类型的静态方法。
|
||||
- **防止回调 `this` 上下文丢失（核心规范）**：在传递服务类的静态方法作为组件事件回调（如 `onClick`）或 React Query 的 `mutationFn`/`queryFn` 时，**禁止直接传递静态方法引用**（如 `mutationFn: DnsAccountService.create`），必须使用箭头函数包裹以防止 `this` 上下文丢失导致运行时崩溃（如 `mutationFn: (payload) => DnsAccountService.create(payload)`）。
|
||||
- 在 `frontend/lib/services/index.ts` 中注册新服务。
|
||||
- 继承 `BaseService`，定义 `basePath`，有类型静态方法；在 `frontend/lib/services/index.ts` 注册。
|
||||
- 回调/`mutationFn`/`queryFn` **禁止**直接传静态方法引用（丢 `this`）；用箭头：`(p) => XxxService.create(p)`。
|
||||
|
||||
+61
-106
@@ -2,9 +2,9 @@
|
||||
|
||||
# OpenFlare
|
||||
|
||||
**[English](./README.en.md) | [📖 中文](./README.md)**
|
||||
**[📖 中文](./README.md) | [English](./README.en.md)**
|
||||
|
||||
OpenFlare is an open-source CDN orchestration and edge security platform. It supports reverse proxies, centralized configuration synchronization, secure intranet penetration (Tunnels), dynamic WAF protection, and anti-CC challenges.
|
||||
OpenFlare is an open-source CDN orchestration and edge security platform. It supports reverse proxy, centralized configuration synchronization, in-network tunneling (Tunnels), dynamic WAF protection, and CC defense challenges.
|
||||
|
||||
</div>
|
||||
|
||||
@@ -21,37 +21,67 @@ OpenFlare is an open-source CDN orchestration and edge security platform. It sup
|
||||
</p>
|
||||
|
||||
> [!WARNING]
|
||||
> After logging in for the first time with the `root` user, make sure to change the default password `123456`.
|
||||
>
|
||||
> The BETA version is a temporary product for the development and testing phase. It may contain unknown issues and should not be used in production environments.
|
||||
> After the first login with the `admin` user, you must change the default password `12345678`.
|
||||
>
|
||||
> The BETA version is a temporary product in the development and testing stage and may have unknown issues. It should not be used in production environments.
|
||||
|
||||
## Documentation
|
||||
|
||||
**https://open-flare.pages.dev**
|
||||
|
||||
Quick links:
|
||||
Common entry points:
|
||||
|
||||
* [Quick Start](https://open-flare.pages.dev/en/guide/quick-start)
|
||||
* [Deployment Guide](https://open-flare.pages.dev/en/deployment/deployment)
|
||||
* [Quick Start](https://open-flare.pages.dev/guide/quick-start)
|
||||
* [Deployment Guide](https://open-flare.pages.dev/deployment/deployment)
|
||||
* [Configuration Reference](https://open-flare.pages.dev/reference/configuration)
|
||||
* [System Design](https://open-flare.pages.dev/design/)
|
||||
|
||||
## Core Features
|
||||
## Core Capabilities
|
||||
|
||||
* **Reverse Proxy Management**: Website rules as the aggregation boundary, supporting multi-domain binding and multi-upstream load balancing with unified management of all OpenResty node configurations.
|
||||
* **Immutable Config Version Control**: Full-snapshot publish model based on version numbers (`YYYYMMDD-NNN`), with pre-publish diff preview, a single globally active version, and one-click sub-second rollback.
|
||||
* **Secure Intranet Penetration (Tunnels)**: An open-source alternative to Cloudflare Tunnels. Securely expose local intranet Web services to the public network via Relay and OpenFlared clients — no public IP or open inbound ports required.
|
||||
* **Edge WAF Safety Protection**: Provides global and custom rule groups, supporting manual/automatic/subscription IP groups, MaxMind GeoIP country-level access control, Checksum-based differential IP group sync (no Nginx reload), and custom block responses.
|
||||
* **Anti-CC & Human-Machine Challenge (PoW)**: Built-in high-performance client-side cryptographic Proof of Work challenges (similar to Turnstile) to block and intercept botnets and scrapers at the gateway edge in seconds.
|
||||
* **Pages Static Hosting**: Upload pre-built ZIP packages directly; edge Agents pull and serve them via local OpenResty, with SPA Fallback and built-in API reverse proxy configuration.
|
||||
* **Automated TLS Certificate Management**: Supports dynamic certificate upload, automatic multi-domain certificate matching and binding, and ACME-based automatic issuance and renewal via Let's Encrypt.
|
||||
* **Uptime Kuma Monitoring Sync**: Integrates with Uptime Kuma to automatically sync the monitoring site list using differential updates, providing real-time awareness of node availability and service health.
|
||||
* **SSO Single Sign-On**: Supports GitHub OAuth and standard OIDC protocol for seamless integration with enterprise identity providers.
|
||||
* **Unified Observability**: Aggregates node request metrics, real-time access log details, host/Nginx resource snapshots, health events, and a re-upload buffer for network fluctuations.
|
||||
* **Reverse Proxy Configuration Management**: Uses website rules as the aggregation boundary, supports multi-domain binding and multi-upstream load balancing, and centrally manages reverse proxy configurations for all OpenResty nodes.
|
||||
* **Secure In-Network Tunneling (Tunnels)**: Open-source version of Cloudflare Tunnels. No public IP or exposed inbound ports are required. Securely reverse-proxy internal web services to the public internet through Relay relay nodes and OpenFlared clients.
|
||||
* **Edge WAF Security Protection**: Provides global and custom rule groups, supports manual/auto/subscription-type IP groups, MaxMind GeoIP national-level geographic access control, IP group member Checksum differential synchronization (no Nginx reload required), and custom blocking responses.
|
||||
* **CC Defense and Human-Computer Challenge (PoW)**: Built-in high-performance client-side cryptography Proof of Work challenge (similar to Turnstile). Secures high-speed interception and blocking of zombie networks and crawlers at the gateway edge.
|
||||
* **Pages Static Hosting**: Supports uploading or synchronizing pre-built artifacts from restricted Remote URLs or public GitHub Release assets. GitHub latest can be checked periodically and optionally auto-published. All sources are unified to generate immutable deployments, pulled by the edge Agent and served locally by OpenResty, supporting rollbacks, SPA Fallback, and API reverse proxy.
|
||||
* **TLS Certificate Automation**: Supports dynamic certificate uploads, automatic multi-domain certificate matching and binding, and automatic issuance and renewal of certificates from Let's Encrypt via the ACME protocol.
|
||||
* **Uptime Kuma Monitoring Synchronization**: Integrated with Uptime Kuma to automatically perform differential synchronization of monitoring site lists, real-time awareness of node availability and service status.
|
||||
* **SSO Single Sign-On**: Supports GitHub OAuth and standard OIDC protocol for seamless integration with enterprise identity providers to achieve unified login.
|
||||
* **Unified Observability**: Aggregates node request metrics, real-time access log details, host and Nginx resource snapshots, health events, and network fluctuation replenishment buffers.
|
||||
|
||||
## Interface Preview
|
||||
|
||||
### Dashboard Overview
|
||||
|
||||
|
||||
|
||||
### Access Logs
|
||||
|
||||
|
||||
|
||||
### WAF Protection
|
||||
|
||||
|
||||
|
||||
## Quick Start
|
||||
|
||||
### 1. Launch Server
|
||||
### Hardware Configuration Recommendations
|
||||
|
||||
| Component | Minimum Hardware Requirements | Recommended Hardware Requirements | Notes |
|
||||
|------------------------|-----------------------------------|-----------------------------------|-------|
|
||||
| **Server Control Plane** | 1 CPU core / 2 GB RAM / 20 GB disk | 2 CPU cores / 4 GB RAM / 50 GB+ disk | Disk usage should be expanded reasonably based on access log retention duration and concurrent traffic |
|
||||
| **Agent Data Plane** | 1 CPU core / 512 MB RAM / 2 GB disk | 2 CPU cores / 2 GB RAM / 10 GB+ disk | Expanded based on OpenResty concurrent proxy connections and WAF interception processing |
|
||||
| **Relay Relay Node** | 1 CPU core / 1 GB RAM / 5 GB disk | 2 CPU cores / 2 GB RAM / 20 GB disk | frps transmission relay throughput is mainly limited by bandwidth and CPU throughput |
|
||||
| **OpenFlared Client** | 1 CPU core / 256 MB RAM / 1 GB disk | 1 CPU core / 512 MB RAM / 5 GB disk | Runs independently on the internal network with extremely low resource consumption; only network throughput needs to be guaranteed |
|
||||
|
||||
### 1. Start the Server
|
||||
|
||||
Use `docker-compose`:
|
||||
|
||||
```bash
|
||||
# Download environment variable template and create .env file
|
||||
curl -o .env.example https://raw.githubusercontent.com/Rain-kl/OpenFlare/refs/heads/main/.env.example
|
||||
cp .env.example .env
|
||||
```
|
||||
|
||||
```yaml
|
||||
services:
|
||||
@@ -70,8 +100,6 @@ services:
|
||||
condition: service_healthy
|
||||
redis:
|
||||
condition: service_healthy
|
||||
clickhouse:
|
||||
condition: service_healthy
|
||||
|
||||
postgres:
|
||||
image: postgres:17-alpine
|
||||
@@ -101,118 +129,45 @@ services:
|
||||
retries: 5
|
||||
start_period: 5s
|
||||
|
||||
clickhouse:
|
||||
image: clickhouse/clickhouse-server:25.3-alpine
|
||||
restart: unless-stopped
|
||||
environment:
|
||||
CLICKHOUSE_DB: ${CLICKHOUSE_NAME:-openflare}
|
||||
CLICKHOUSE_USER: ${CLICKHOUSE_USERNAME:-default}
|
||||
CLICKHOUSE_PASSWORD: ${CLICKHOUSE_PASSWORD:-replace-with-clickhouse-password}
|
||||
CLICKHOUSE_DEFAULT_ACCESS_MANAGEMENT: 1
|
||||
TZ: ${TZ:-Asia/Shanghai}
|
||||
volumes:
|
||||
- openflare_clickhouse_data:/var/lib/clickhouse
|
||||
healthcheck:
|
||||
test: ["CMD", "clickhouse-client", "--user", "${CLICKHOUSE_USERNAME:-default}", "--password", "${CLICKHOUSE_PASSWORD:-replace-with-clickhouse-password}", "--query", "SELECT 1"]
|
||||
interval: 10s
|
||||
timeout: 5s
|
||||
retries: 5
|
||||
start_period: 15s
|
||||
|
||||
volumes:
|
||||
openflare_uploads:
|
||||
openflare_postgres_data:
|
||||
openflare_redis_data:
|
||||
openflare_clickhouse_data:
|
||||
```
|
||||
|
||||
```bash
|
||||
docker compose up -d
|
||||
```
|
||||
See the [deployment documentation](https://open-flare.pages.dev/deployment/deployment) for details.
|
||||
|
||||
Access at: `http://localhost:3000`
|
||||
Access address: `http://localhost:3000`
|
||||
|
||||
Default credentials:
|
||||
Default account:
|
||||
|
||||
* Username: `root`
|
||||
* Password: `123456`
|
||||
* Username: `admin`
|
||||
* Password: `12345678`
|
||||
|
||||
### 2. Install Agent
|
||||
|
||||
Before installing an Agent, please install OpenResty on the target node first, or use the Agent Docker image with OpenResty built-in.
|
||||
Before installing the Agent, first install OpenResty on the node or use the built-in OpenResty Agent Docker image.
|
||||
|
||||
You can copy the installation command from **Node Management -> Details -> Node Info -> Node Token & Deployment** in the control panel, or directly use the scripts below:
|
||||
You can copy the installation command from the control panel's **Nodes Management -> Details -> Node Information -> Node ID and Deployment**, or use the script below:
|
||||
|
||||
#### Docker Deployment
|
||||
|
||||
For Docker deployment, you can directly run the Agent image:
|
||||
Docker deployment can directly run the Agent image:
|
||||
|
||||
```bash
|
||||
docker pull ghcr.io/rain-kl/openflare-agent:latest
|
||||
docker rm -f openflare-agent 2>/dev/null || true
|
||||
docker run -d --name openflare-agent --restart unless-stopped \
|
||||
-p 80:80 -p 443:443/tcp -p 443:443/udp \
|
||||
-v openflare-agent-pages:/data/var/lib/openflare/pages \
|
||||
-e OPENFLARE_SERVER_URL=http://your-server:3000 \
|
||||
-e OPENFLARE_AGENT_TOKEN=YOUR_AGENT_TOKEN \
|
||||
ghcr.io/rain-kl/openflare-agent:latest
|
||||
```
|
||||
|
||||
#### Local Installation
|
||||
## Open Source License
|
||||
|
||||
Using `discovery_token` to register:
|
||||
|
||||
```bash
|
||||
curl -fsSL https://raw.githubusercontent.com/Rain-kl/OpenFlare/main/scripts/install-agent.sh | bash -s -- \
|
||||
--server-url http://your-server:3000 \
|
||||
--discovery-token YOUR_DISCOVERY_TOKEN
|
||||
```
|
||||
|
||||
Using node-specific `agent_token`:
|
||||
|
||||
```bash
|
||||
curl -fsSL https://raw.githubusercontent.com/Rain-kl/OpenFlare/main/scripts/install-agent.sh | bash -s -- \
|
||||
--server-url http://your-server:3000 \
|
||||
--agent-token YOUR_AGENT_TOKEN
|
||||
```
|
||||
|
||||
The installation script defaults to `/opt/openflare-agent`, creates a `openflare-agent.service`, automatically searches for `openresty`, and can be executed repeatedly to reinstall or upgrade the Agent.
|
||||
|
||||
### 3. Uninstall Agent
|
||||
|
||||
To completely uninstall the Agent and clear local data, run:
|
||||
|
||||
```bash
|
||||
curl -fsSL https://raw.githubusercontent.com/Rain-kl/OpenFlare/main/scripts/uninstall-agent.sh | bash
|
||||
```
|
||||
|
||||
The uninstallation script will stop and remove the `openflare-agent.service`, and delete the entire `/opt/openflare-agent` directory. It will not delete the local OpenResty installation.
|
||||
|
||||
### 4. Publish Your First Configuration
|
||||
|
||||
1. Log in to the management panel and add a reverse proxy rule.
|
||||
2. View the preview or change summary before publishing.
|
||||
3. Activate the new version.
|
||||
4. Agents will receive the configuration and apply it via WebSocket notification or subsequent heartbeats.
|
||||
|
||||
The version number format is fixed as `YYYYMMDD-NNN`. Historical versions are immutable, and rollback is achieved by reactivating an older version.
|
||||
|
||||
## UI Preview
|
||||
|
||||
### Dashboard Overview
|
||||
|
||||
|
||||
|
||||
### Node Details
|
||||
|
||||
|
||||
|
||||
### Proxy Configuration
|
||||
|
||||
|
||||
|
||||
## License
|
||||
|
||||
This project is licensed under [Apache License 2.0](./LICENSE).
|
||||
This project is licensed under the [Apache License 2.0](./LICENSE).
|
||||
|
||||
## Star History
|
||||
|
||||
|
||||
@@ -54,16 +54,25 @@ OpenFlare 是开源 CDN 编排与边缘安全平台。它支持反向代理、
|
||||
|
||||
|
||||
|
||||
### 节点详情
|
||||
### 访问日志
|
||||
|
||||
|
||||
|
||||
|
||||
### 配置新增
|
||||
### WAF 防护
|
||||
|
||||
|
||||
|
||||
|
||||
## 快速开始
|
||||
|
||||
### 硬件配置推荐
|
||||
|
||||
| 组件 | 最低硬件配额 | 推荐硬件配额 | 说明 |
|
||||
| --- |-------------------------------| --- | --- |
|
||||
| **Server 控制面** | 1 核 CPU / 2 GB 内存 / 20 GB 磁盘 | 2 核 CPU / 4 GB 内存 / 50 GB+ 磁盘 | 磁盘用量需根据访问日志留存时长与并发流量合理扩容 |
|
||||
| **Agent 数据面** | 1 核 CPU / 512 MB 内存 / 2 GB 磁盘 | 2 核 CPU / 2 GB 内存 / 10 GB+ 磁盘 | 根据 OpenResty 的并发代理连接量与 WAF 拦截处理扩容 |
|
||||
| **Relay 中继节点**| 1 核 CPU / 1 GB 内存 / 5 GB 磁盘 | 2 核 CPU / 2 GB 内存 / 20 GB 磁盘 | frps 传输中继吞吐量主要受带宽与 CPU 吞吐能力限制 |
|
||||
| **OpenFlared 客户端**| 1 核 CPU / 256 MB 内存 / 1 GB 磁盘 | 1 核 CPU / 512 MB 内存 / 5 GB 磁盘 | 独立运行于内网，自身资源占用极小，保障网络吞吐即可 |
|
||||
|
||||
### 1. 启动 Server
|
||||
|
||||
使用 docker-compose
|
||||
@@ -72,11 +81,6 @@ OpenFlare 是开源 CDN 编排与边缘安全平台。它支持反向代理、
|
||||
# 下载环境变量模板并创建 .env 文件
|
||||
curl -o .env.example https://raw.githubusercontent.com/Rain-kl/OpenFlare/refs/heads/main/.env.example
|
||||
cp .env.example .env
|
||||
|
||||
# ClickHouse 服务端：curl performance.xml 到 ./config/clickhouse，并以单文件方式挂载到 config.d
|
||||
mkdir -p ./config/clickhouse
|
||||
curl -fsSL -o ./config/clickhouse/performance.xml \
|
||||
https://raw.githubusercontent.com/Rain-kl/OpenFlare/refs/heads/main/config/clickhouse/performance.xml
|
||||
```
|
||||
|
||||
```yaml
|
||||
@@ -96,8 +100,6 @@ services:
|
||||
condition: service_healthy
|
||||
redis:
|
||||
condition: service_healthy
|
||||
clickhouse:
|
||||
condition: service_healthy
|
||||
|
||||
postgres:
|
||||
image: postgres:17-alpine
|
||||
@@ -127,34 +129,10 @@ services:
|
||||
retries: 5
|
||||
start_period: 5s
|
||||
|
||||
clickhouse:
|
||||
image: clickhouse/clickhouse-server:25.3-alpine
|
||||
restart: unless-stopped
|
||||
environment:
|
||||
CLICKHOUSE_DB: ${CLICKHOUSE_NAME:-openflare}
|
||||
CLICKHOUSE_USER: ${CLICKHOUSE_USERNAME:-default}
|
||||
CLICKHOUSE_PASSWORD: ${CLICKHOUSE_PASSWORD:-replace-with-clickhouse-password}
|
||||
CLICKHOUSE_DEFAULT_ACCESS_MANAGEMENT: 1
|
||||
TZ: ${TZ:-Asia/Shanghai}
|
||||
ulimits:
|
||||
nofile:
|
||||
soft: 262144
|
||||
hard: 262144
|
||||
volumes:
|
||||
- openflare_clickhouse_data:/var/lib/clickhouse
|
||||
- ./config/clickhouse/performance.xml:/etc/clickhouse-server/config.d/performance.xml:ro
|
||||
healthcheck:
|
||||
test: ["CMD", "clickhouse-client", "--user", "${CLICKHOUSE_USERNAME:-default}", "--password", "${CLICKHOUSE_PASSWORD:-replace-with-clickhouse-password}", "--query", "SELECT 1"]
|
||||
interval: 10s
|
||||
timeout: 5s
|
||||
retries: 5
|
||||
start_period: 15s
|
||||
|
||||
volumes:
|
||||
openflare_uploads:
|
||||
openflare_postgres_data:
|
||||
openflare_redis_data:
|
||||
openflare_clickhouse_data:
|
||||
```
|
||||
|
||||
详细部署说明见 [部署文档](https://open-flare.pages.dev/deployment/deployment)。
|
||||
|
||||
+4
-2
@@ -99,10 +99,12 @@ otel:
|
||||
tracer_name: "github.com/Rain-kl/OpenFlare" # Global tracer instrumentation name
|
||||
|
||||
|
||||
# ─── ClickHouse (required) ──────────────────────────────────────────────────────
|
||||
# ─── ClickHouse (optional) ─────────────────────────────────────────────────────
|
||||
# Analytics / observability OLAP store. Telemetry writes are best-effort (async batch).
|
||||
# 默认关闭：缺失本配置块或 enabled: false 时不启用 ClickHouse，日志/指标由主库承担；
|
||||
# 设置 CLICKHOUSE_HOST 或 CLICKHOUSE_ENABLED=true 可经环境变量启用。
|
||||
clickhouse:
|
||||
enabled: true
|
||||
enabled: false
|
||||
hosts:
|
||||
- "127.0.0.1:9000" # compose 内应用可用 clickhouse:9000（经 CLICKHOUSE_HOST）
|
||||
username: "default"
|
||||
|
||||
+1
-1
@@ -110,7 +110,7 @@ services:
|
||||
- ./data/agent/:/data
|
||||
environment:
|
||||
OPENFLARE_SERVER_URL: "http://host.docker.internal:3000"
|
||||
OPENFLARE_AGENT_TOKEN: "af2fb112f36a0055ec25dd164c908fea"
|
||||
OPENFLARE_AGENT_TOKEN: "7c7c4c13df0f3a77866bcd8cde492610"
|
||||
LOG_LEVEL: "debug"
|
||||
extra_hosts:
|
||||
- "host.docker.internal:host-gateway"
|
||||
|
||||
+13
-4
@@ -1,4 +1,5 @@
|
||||
# syntax=docker/dockerfile:1.7
|
||||
# Agent image: slim binary + MMDB files on disk (not embedded in the binary).
|
||||
ARG VERSION=dev
|
||||
|
||||
FROM golang:1.25-alpine AS builder
|
||||
@@ -17,12 +18,14 @@ RUN --mount=type=cache,target=/go/pkg/mod \
|
||||
go mod download
|
||||
|
||||
COPY . .
|
||||
RUN apk add --no-cache bash curl \
|
||||
&& bash scripts/fetch-agent-geoip-mmdb.sh
|
||||
RUN --mount=type=cache,target=/go/pkg/mod \
|
||||
--mount=type=cache,target=/root/.cache/go-build \
|
||||
go build -trimpath -ldflags "-s -w -X 'github.com/Rain-kl/Wavelet/internal/apps/agent/config.Version=$VERSION'" -o /build/bin/openflare-agent ./cmd/agent/main.go
|
||||
|
||||
# Fetch MMDB into dist/geoip for COPY into the runtime image (not go:embed).
|
||||
RUN apk add --no-cache bash curl \
|
||||
&& bash scripts/fetch-agent-geoip-mmdb.sh
|
||||
|
||||
FROM openresty/openresty:alpine
|
||||
|
||||
RUN apk add --no-cache ca-certificates tzdata perl libmaxminddb su-exec libcap \
|
||||
@@ -30,7 +33,7 @@ RUN apk add --no-cache ca-certificates tzdata perl libmaxminddb su-exec libcap \
|
||||
&& opm get anjia0532/lua-resty-maxminddb \
|
||||
&& addgroup -S openflare \
|
||||
&& adduser -S -G openflare -H -h /data -s /sbin/nologin openflare \
|
||||
&& mkdir -p /etc/openflare /data \
|
||||
&& mkdir -p /etc/openflare /data/etc/openflare \
|
||||
&& chown -R openflare:openflare /etc/openflare /data \
|
||||
&& setcap 'cap_net_bind_service=+ep' /usr/local/openresty/nginx/sbin/nginx
|
||||
|
||||
@@ -38,9 +41,15 @@ ENV OPENFLARE_OPENRESTY_PATH=openresty \
|
||||
OPENFLARE_DATA_DIR=/data
|
||||
|
||||
COPY --from=builder /build/bin/openflare-agent /usr/local/bin/openflare-agent
|
||||
# Default agent paths: data_dir/etc/openflare/GeoLite2-*.mmdb
|
||||
COPY --from=builder /build/dist/geoip/GeoLite2-Country.mmdb /data/etc/openflare/GeoLite2-Country.mmdb
|
||||
COPY --from=builder /build/dist/geoip/GeoLite2-City.mmdb /data/etc/openflare/GeoLite2-City.mmdb
|
||||
RUN chown openflare:openflare /data/etc/openflare/GeoLite2-Country.mmdb /data/etc/openflare/GeoLite2-City.mmdb \
|
||||
&& chmod 644 /data/etc/openflare/GeoLite2-Country.mmdb /data/etc/openflare/GeoLite2-City.mmdb
|
||||
|
||||
COPY scripts/agent-entrypoint.sh /usr/local/bin/openflare-agent-entrypoint.sh
|
||||
RUN chmod +x /usr/local/bin/openflare-agent-entrypoint.sh
|
||||
|
||||
EXPOSE 80 443 18081
|
||||
ENTRYPOINT ["/usr/local/bin/openflare-agent-entrypoint.sh"]
|
||||
CMD ["-config", "/etc/openflare/agent.json"]
|
||||
CMD ["-config", "/etc/openflare/agent.json"]
|
||||
|
||||
@@ -14,7 +14,8 @@ export default defineConfig({
|
||||
'components/**',
|
||||
'snippets/**',
|
||||
'plan/**',
|
||||
'guideline/**'
|
||||
'guideline/**',
|
||||
'superpowers/**'
|
||||
],
|
||||
|
||||
markdown: {
|
||||
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 58 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 67 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 77 KiB |
+71
-9
@@ -11,31 +11,93 @@ sidebar: false
|
||||
## 重大变更
|
||||
|
||||
> [!IMPORTANT]
|
||||
>
|
||||
> 3.1.2 版本更新了 CLickHouse 部署配置。
|
||||
>
|
||||
> 3.0.0 版本为 Wavelet 平台迁移与架构重构版本，涉及数据库表结构、环境变量以及前后端底层架构的重大变更。请务必在升级前备份数据库，并且更新到 V2.3.4。
|
||||
> 目前已知的兼容性问题：
|
||||
>
|
||||
> - Pages 无法迁移, 升级前请先手动下载并备份 Pages 静态站点的 ZIP 包，升级后重新创建。
|
||||
> - 性能调优参数重置, 升级后请重新配置
|
||||
>
|
||||
>3.5.1 版本解耦了日志存储，ClickHouse 变为可选项，如果想切换数据库, 点击 「任务管理」 -> 「切换日志数据库」任务，按提示迁移数据并切换主库。
|
||||
>
|
||||
|
||||
## [unreleased]
|
||||
|
||||
## [v3.5.3] - 2026-08-13
|
||||
|
||||
### 新增
|
||||
- 访问日志「日志明细」支持按 HTTP 状态码筛选，可直接输入任意状态码。
|
||||
- 访问日志「日志明细」支持自定义时间范围筛选，可按起止时间检索日志。
|
||||
- 首页看板改版：24 小时请求趋势拆分展示请求总量与 2xx/4xx/5xx 状态码类请求量并独占一行；移除宿主机磁盘指标，24 小时容量趋势（CPU/内存）并入业务流量卡片展示。
|
||||
|
||||
### 🛠 修复
|
||||
- 修复首页「来源分布」卡片在 PostgreSQL/SQLite 日志库下无数据的问题。
|
||||
- 修复源站错误页「仅针对 GET 请求」未真正透传非 GET 响应的问题：POST/PUT 等非 GET 请求现可完整看到源站原始报错内容。
|
||||
|
||||
## [v3.5.2] - 2026-08-09
|
||||
|
||||
### 🛠 修复
|
||||
- 修复 PostgreSQL 作为日志库时节点访问日志/可观测指标/用户访问日志批量写入失败的问题，现可正常写入。
|
||||
|
||||
## [v3.5.1] - 2026-08-09
|
||||
|
||||
### 新增
|
||||
- 日志存储解耦：ClickHouse 变为可选项，不启用时由 PostgreSQL/SQLite 承担全部日志功能；新增「切换日志数据库」任务支持 PostgreSQL/SQLite 与 ClickHouse 间数据迁移（迁移期间冻结日志写入，成功后自动切换主库并保留源数据）；`log_database` / `log_db_migration` 设为受保护配置；ClickHouse 改为默认关闭。
|
||||
- 新增 PostgreSQL/SQLite 日志存储实现：节点访问日志按月分区，统计查询合并为单次扫描、IP 汇总归属地取查询窗口内最新记录、WAF 按 IP 聚合减少扫描次数，并新增 `logged_at` 前导索引与主机名小写表达式索引；过期清理直接删除完全过期的整月分区，启动时兜底预建当月及未来 2 个月分区。
|
||||
- 性能指标与访问日志的保留时长解耦：新增三库共用的 `metric_retention_days` 配置（默认 3 天），每日垃圾清理按独立短留存清理指标快照。
|
||||
|
||||
### 🛠 修复
|
||||
- 修复 UptimeKuma 同步调试日志泄露凭据：Socket.IO 事件日志不再打印 payload 内容（仅记录长度），避免凭据进入日志。
|
||||
- 修复日志保留天数配置继承旧键导致的误删风险：`log_retention_days_*` 不再继承 `database_auto_cleanup_retention_days`，统一默认 30 天。
|
||||
|
||||
### ⚡️ 优化与改进
|
||||
- 系统定期垃圾清理由每 2 小时改为每日执行一次（凌晨 3 点，Asia/Shanghai），降低非必要高频扫描。
|
||||
|
||||
### 💄 其他/体验
|
||||
- 服务工作者（SW）注入挑战页改为前台无感知：不再显示「加载中…」文案，页面空白，仅通过浏览器控制台输出 `[sw-challenge]` 调试信息，注入过程不打扰访客。
|
||||
- 用户访问日志（`w_user_access_logs`）记录禁用：不再采集与写入新的用户访问日志，存量数据与管理端访问日志统计页面保留。
|
||||
|
||||
|
||||
## [v3.5.0] - 2026-08-08
|
||||
|
||||
### 🛠 修复
|
||||
- 修复 PoW 挑战页潜在 XSS 风险，状态与错误文案改用纯文本渲染，并限制跳转 URL 仅允许 http/https 协议。
|
||||
- 修复邮件发送的邮件头注入风险，写入邮件头前自动清除 CR/LF 换行符（CWE-93）。
|
||||
- 修复 UptimeKuma 同步调试日志泄露凭据问题，输出日志前对密码和 Token 等敏感字段打码。
|
||||
|
||||
### ⚡️ 优化与改进
|
||||
- 新增 Service Worker 离线兜底功能，为启用 HTTPS 的网站自动下发 Service Worker 并缓存离线页，域名不可达时展示离线兜底页面。
|
||||
- 重构响应页面设置，将源站错误页与 Service Worker 离线页整合至统一的「响应页面」（/responses）标签页，并增加 URL 查询参数 tab 状态同步。
|
||||
|
||||
### 💄 其他/体验
|
||||
- 新增离线页内置预制模板套件（「极简白底」、「线框拓扑」、「包豪斯」），与源站错误页模板风格保持一致，支持编辑界面一键加载与预览。
|
||||
|
||||
## [v3.4.5] - 2026-08-08
|
||||
|
||||
### 改进
|
||||
|
||||
- 源站错误页支持「仅针对 GET 请求」：开启后仅对 GET 的匹配错误状态码返回自定义错误页，其它 HTTP 方法透传源站响应。
|
||||
- 升级后端 Go 依赖至最新稳定版（Gin、GORM、OpenTelemetry、ClickHouse 驱动、AWS SDK、Redis 客户端等），并完成升级兼容性适配：OpenTelemetry 资源 schema 与语义约定版本对齐，ClickHouse 驱动新增格式查询/插入接口的测试替身补齐。
|
||||
- 升级前端 npm 依赖至最新稳定版（Next.js 16.3、React 19.2、recharts 3、react-day-picker 10、lucide-react 1.x、Tailwind CSS 4.3 等），适配图表/日历组件 API 变化，并将 ESLint 配置迁移为 eslint-config-next 16 的 flat config。
|
||||
|
||||
- Agent 不再将 GeoLite2 Country/City MMDB 嵌入二进制：Docker 镜像在默认数据目录 COPY 数据库文件，裸二进制首次启动时按需下载，显著减小 Agent 包体积；OpenResty 仍从磁盘路径读取 MMDB。Server 控制面仍仅内嵌 Country MMDB（不含 City），供可选 MaxMind 提供方离线初始化。
|
||||
|
||||
## [v3.4.4] - 2026-08-06
|
||||
|
||||
### 新增
|
||||
|
||||
- 新增全局源站错误页：可在「网站管理 → 错误页」配置开关、触发状态码（支持 `500-599` 区间与单码）与自定义 HTML；默认启用 OpenFlare 极简错误页并保持真实 HTTP 状态码，修改后随配置版本发布下发到边缘，关闭后恢复透传。
|
||||
- 源站错误页支持「仅针对 GET 请求」：开启后仅对 GET 的匹配错误状态码返回自定义错误页，其它 HTTP 方法透传源站响应。
|
||||
- 新增 Cloudflare DNS 指向管理：可复用现有 Cloudflare DNS 账号或配置独立 Token，按分组将 ZoneDomain 的单条 A 记录异步同步到边缘节点 IPv4，并支持成员橙云、同步状态与节点 IP 变更联动。
|
||||
|
||||
### 修复
|
||||
|
||||
- 修复源站错误页在边缘返回 HTTP 200、页面状态码显示异常（如 0）的问题：错误响应现在正确透传上游状态码，并在页面中展示真实状态码。
|
||||
- 修复 Agent 在配置已对齐但磁盘校验和不一致时，Pages 等对账成功后仍保留 `LastError` 的问题，避免偶发网络失败被健康事件长期显示为「活动中」且无法自动恢复。
|
||||
|
||||
### 改进
|
||||
|
||||
- 删除、撤销与未保存离开等确认操作统一改用页面内 AlertDialog，不再使用浏览器原生 `confirm` 弹窗，交互风格与系统其余对话框保持一致。
|
||||
- Cloudflare 分组添加域名成员时支持按顶级域分层展示、搜索筛选与批量勾选，可一次加入多个域名并排队同步。
|
||||
- Cloudflare 首页展示域名同步（sync_member）与分组同步（sync_group）任务执行记录，可筛选状态、查看详情与失败重试。
|
||||
- Cloudflare 域名/分组同步任务日志补充域名、分组、生效节点 IP、橙云状态及逐域名进度等关键信息，便于排查同步结果。
|
||||
- Cloudflare 域名同步与分组同步任务改为可在任务管理中调度的标准任务类型，并提供成员 ID / 分组 ID 参数表单。
|
||||
- Cloudflare 首页直接提供指向分组管理，并为分组详情增加自动刷新与手动刷新，减少页面跳转并及时展示同步状态。
|
||||
- 统一数据访问分层：业务持久化经 `internal/repository`，`internal/model` 仅保留实体与无 IO 领域规则，避免双轨 CRUD 与职责混淆。
|
||||
- 构建检查增加 `internal/model` 禁止直接访问数据库/Redis 的架构守卫，并收敛 model 与 repository 的错误文案定义边界。
|
||||
|
||||
## [v3.4.3] - 2026-07-24
|
||||
|
||||
|
||||
@@ -136,55 +136,6 @@ docker run -d --name openflare-agent --restart unless-stopped \
|
||||
> **Pages 持久化**
|
||||
> 默认将 Pages 部署目录挂载到 Docker 命名卷 `openflare-agent-pages`（容器内路径 `/data/var/lib/openflare/pages`）。重建或升级 Agent 容器时无需重新拉取静态站点包。
|
||||
|
||||
> [!NOTE]
|
||||
> **非 Root 安全加固运行**
|
||||
> Agent 容器内部已完成安全加固，在启动后会统一以低权限非 root 用户 `openflare` 运行。
|
||||
> 容器已内置了 `cap_net_bind_service` 内核能力，使得低权限进程依然能够正常监听宿主机的 `80` 和 `443` 特权端口。
|
||||
> 同时，OpenResty 运行时所需的各种临时路径（包括 PID 路径、各类临时缓存目录如 `client_body_temp_path`、`proxy_temp_path` 等）都由 Agent 控制器动态渲染并自动重定向至容器内的 `/data` 目录，彻底避免在非 root 权限运行时写入默认系统路径而导致的权限拒绝错误（Permission Denied）。
|
||||
> 具体物理缓存写入路径为：
|
||||
> * 临时缓存目录：`/data/var/cache/nginx`
|
||||
> * 代理缓存目录：`/data/var/cache/openflare_proxy`
|
||||
|
||||
## 启动与验证
|
||||
|
||||
systemd 环境：
|
||||
|
||||
```bash
|
||||
systemctl status openflare-agent
|
||||
journalctl -u openflare-agent -f
|
||||
```
|
||||
|
||||
手动启动：
|
||||
|
||||
```bash
|
||||
/opt/openflare-agent/openflare-agent -config /opt/openflare-agent/agent.json
|
||||
```
|
||||
|
||||
源码运行：
|
||||
|
||||
```bash
|
||||
|
||||
export LOG_LEVEL='info'
|
||||
go run ./cmd/agent -config /path/to/agent.json
|
||||
```
|
||||
|
||||
编译后二进制运行：
|
||||
|
||||
```bash
|
||||
|
||||
go build -o openflare-agent ./cmd/agent
|
||||
export LOG_LEVEL='info'
|
||||
./openflare-agent -config /path/to/agent.json
|
||||
```
|
||||
|
||||
在管理端确认：
|
||||
|
||||
| 位置 | 期望结果 |
|
||||
| --- | --- |
|
||||
| 节点列表 | 节点在线 |
|
||||
| 节点详情 | 能看到心跳时间、当前版本和基础资源信息 |
|
||||
| 应用记录 | 发布配置后出现应用结果 |
|
||||
|
||||
## 卸载
|
||||
|
||||
### 交互式卸载 (推荐)
|
||||
@@ -195,38 +146,14 @@ export LOG_LEVEL='info'
|
||||
curl -fsSL https://raw.githubusercontent.com/Rain-kl/OpenFlare/main/scripts/uninstall-agent.sh | bash
|
||||
```
|
||||
|
||||
### 自动化 (非交互式) 卸载
|
||||
### 卸载
|
||||
|
||||
使用命令行传参进行无人值守卸载。
|
||||
|
||||
本地卸载（默认）：
|
||||
|
||||
```bash
|
||||
curl -fsSL https://raw.githubusercontent.com/Rain-kl/OpenFlare/main/scripts/uninstall-agent.sh | bash -s -- --install-dir /opt/openflare-agent
|
||||
```
|
||||
|
||||
Docker 容器卸载：
|
||||
|
||||
```bash
|
||||
curl -fsSL https://raw.githubusercontent.com/Rain-kl/OpenFlare/main/scripts/uninstall-agent.sh | bash -s -- --docker
|
||||
```
|
||||
|
||||
支持参数：
|
||||
|
||||
| 参数 | 说明 |
|
||||
| --- | --- |
|
||||
| `--install-dir` | 安装目录，默认 `/opt/openflare-agent`（仅本地卸载生效） |
|
||||
| `--service-name` | systemd 服务名，默认 `openflare-agent`（仅本地卸载生效） |
|
||||
| `--docker` | 使用 Docker 容器方式卸载 |
|
||||
| `--method` | 卸载方式，可选 `local` 或 `docker`（默认 `local`） |
|
||||
|
||||
本地卸载只会移除 Agent 服务、进程和安装目录，不会删除本机 OpenResty。Docker 卸载会停止并删除 `openflare-agent` 容器，交互模式下还可以选择是否清理对应的 Docker 镜像。
|
||||
停止并删除 `openflare-agent` 容器即可
|
||||
|
||||
## 常见问题
|
||||
|
||||
| 现象 | 处理步骤 |
|
||||
| --- | --- |
|
||||
| `agent_token 和 discovery_token 不能同时为空` | 检查 `agent.json` 至少配置了一个 Token |
|
||||
| 节点一直离线 | 在 Agent 节点执行 `curl -I http://your-server:3000`，确认 Server 地址可达 |
|
||||
| OpenResty 没有启动 | 查看 `journalctl -u openflare-agent`，确认 `openresty_path` 可执行，80/443 端口未被占用，且运行用户（如 `openflare`）对数据目录具有读写权限 |
|
||||
| 发布后重复失败 | Agent 会阻断同一 `version + checksum` 的重复应用；需要修正配置后重新发布，或激活旧版本回滚 |
|
||||
| 现象 | 处理步骤 |
|
||||
| --- |---------------------------------------------------------------------------------------------------------|
|
||||
| `agent_token 和 discovery_token 不能同时为空` | 检查 `agent.json` 至少配置了一个 Token |
|
||||
| 节点一直离线 | 在 Agent 节点执行 `curl -I http://your-server:3000`，确认 Server 地址可达 |
|
||||
| 发布后重复失败 | Agent 会阻断同一 `version + checksum` 的重复应用；在节点尝试强制同步,或者重新发布版本 |
|
||||
|
||||
@@ -47,33 +47,13 @@ Internal Service (192.168.x.x)
|
||||
|
||||
## 前置条件
|
||||
|
||||
Server：
|
||||
|
||||
| 项目 | 要求 |
|
||||
| --- | --- |
|
||||
| Go | `1.25+`，仅源码运行需要 |
|
||||
| Node.js | `18+`，仅源码构建管理端需要 |
|
||||
| 数据库 | 可写 SQLite 文件目录，或可访问的 PostgreSQL 实例 |
|
||||
| 端口 | 默认监听 `3000` |
|
||||
|
||||
Agent：
|
||||
|
||||
| 项目 | 要求 |
|
||||
| --- | --- |
|
||||
| 系统 | 安装脚本支持 Linux 和 macOS；systemd 服务仅在 Linux + systemd 环境创建 |
|
||||
| 架构 | `amd64` 或 `arm64` |
|
||||
| OpenResty | 本地部署需要可执行 `openresty`，或通过 `--openresty-path` 指定路径 |
|
||||
| Docker | 仅 Docker 部署 Agent 镜像时需要 |
|
||||
| 网络 | Agent 节点必须能访问 Server 地址 |
|
||||
| GeoIP | WAF 地域规则使用 Agent 本地 MaxMind mmdb；Agent 内置初始库并会定期更新 |
|
||||
|
||||
### 硬件配置推荐
|
||||
|
||||
| 组件 | 最低硬件配额 | 推荐硬件配额 | 说明 |
|
||||
| --- | --- | --- | --- |
|
||||
| **Server 控制面** | 1 核 CPU / 1 GB 内存 / 10 GB 磁盘 | 2 核 CPU / 4 GB 内存 / 50 GB+ 磁盘 | 磁盘用量需根据访问日志留存时长与并发流量合理扩容 |
|
||||
| 组件 | 最低硬件配额 | 推荐硬件配额 | 说明 |
|
||||
| --- |-------------------------------| --- | --- |
|
||||
| **Server 控制面** | 1 核 CPU / 2 GB 内存 / 20 GB 磁盘 | 2 核 CPU / 4 GB 内存 / 50 GB+ 磁盘 | 磁盘用量需根据访问日志留存时长与并发流量合理扩容 |
|
||||
| **Agent 数据面** | 1 核 CPU / 512 MB 内存 / 2 GB 磁盘 | 2 核 CPU / 2 GB 内存 / 10 GB+ 磁盘 | 根据 OpenResty 的并发代理连接量与 WAF 拦截处理扩容 |
|
||||
| **Relay 中继节点**| 1 核 CPU / 1 GB 内存 / 5 GB 磁盘 | 2 核 CPU / 2 GB 内存 / 20 GB 磁盘 | frps 传输中继吞吐量主要受带宽与 CPU 吞吐能力限制 |
|
||||
| **Relay 中继节点**| 1 核 CPU / 1 GB 内存 / 5 GB 磁盘 | 2 核 CPU / 2 GB 内存 / 20 GB 磁盘 | frps 传输中继吞吐量主要受带宽与 CPU 吞吐能力限制 |
|
||||
| **OpenFlared 客户端**| 1 核 CPU / 256 MB 内存 / 1 GB 磁盘 | 1 核 CPU / 512 MB 内存 / 5 GB 磁盘 | 独立运行于内网，自身资源占用极小，保障网络吞吐即可 |
|
||||
|
||||
## Docker Compose 部署 Server
|
||||
@@ -169,41 +149,3 @@ curl -fsSL https://raw.githubusercontent.com/Rain-kl/OpenFlare/main/scripts/inst
|
||||
systemctl status openflare-agent
|
||||
journalctl -u openflare-agent -f
|
||||
```
|
||||
|
||||
## 手动运行 Agent
|
||||
|
||||
源码运行：
|
||||
|
||||
```bash
|
||||
|
||||
export LOG_LEVEL='info'
|
||||
go run ./cmd/agent -config /path/to/agent.json
|
||||
```
|
||||
|
||||
编译后二进制运行：
|
||||
|
||||
```bash
|
||||
|
||||
go build -o openflare-agent ./cmd/agent
|
||||
export LOG_LEVEL='info'
|
||||
./openflare-agent -config /path/to/agent.json
|
||||
```
|
||||
|
||||
最小 `agent.json` 示例：
|
||||
|
||||
```json
|
||||
{
|
||||
"server_url": "http://127.0.0.1:3000",
|
||||
"agent_token": "replace-with-node-auth-token",
|
||||
"data_dir": "./data",
|
||||
"openresty_path": "openresty",
|
||||
"heartbeat_interval": 3000,
|
||||
"request_timeout": 10000
|
||||
}
|
||||
```
|
||||
|
||||
未配置 `openresty_path` 时，Agent 默认调用 `openresty`。
|
||||
|
||||
默认情况下，Agent 在 HTTP 心跳成功后会尝试升级为 WebSocket。升级成功时，Server 发布或激活配置会立即通知 Agent；如果 WebSocket 无法建立或意外断开，Agent 会自动退回 HTTP 心跳同步。
|
||||
|
||||
WAF 地域规则依赖 Agent 本地 `GeoLite2-Country.mmdb`。Agent 启动时会在 `data_dir/etc/openflare/GeoLite2-Country.mmdb` 初始化内置数据库，并按配置周期尝试更新；更新失败只记录警告，不影响配置同步与 OpenResty reload。
|
||||
|
||||
@@ -34,7 +34,7 @@
|
||||
|
||||
---
|
||||
|
||||
## Docker 运行（推荐）
|
||||
## Docker 运行
|
||||
|
||||
Docker 部署是内网运行最简单也最安全的方式。官方的 `openflared` 镜像已经内置了客户端控制器以及 `frpc v0.69.0` 二进制运行时，无需额外搭建环境。
|
||||
|
||||
@@ -51,40 +51,6 @@ docker run -d --name openflared --restart unless-stopped \
|
||||
|
||||
---
|
||||
|
||||
## 宿主机手动运行
|
||||
|
||||
如果您需要直接在内网的 Linux/macOS/Windows 宿主机上独立运行：
|
||||
|
||||
### 1. 编译二进制
|
||||
|
||||
```bash
|
||||
go build -o bin/flared ./cmd/flared
|
||||
```
|
||||
|
||||
### 2. 准备 `flared.json`
|
||||
|
||||
在程序同级目录下创建 `flared.json` 配置文件：
|
||||
|
||||
```json
|
||||
{
|
||||
"server_url": "http://your-server-ip:3000",
|
||||
"tunnel_token": "your-tunnel-auth-token",
|
||||
"frpc_path": "/usr/local/bin/frpc",
|
||||
"data_dir": "./data",
|
||||
"heartbeat_interval": "10s",
|
||||
"sync_interval": "30s"
|
||||
}
|
||||
```
|
||||
|
||||
### 3. 运行服务
|
||||
|
||||
```bash
|
||||
export LOG_LEVEL='info'
|
||||
./flared -config ./flared.json
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 启动与验证
|
||||
|
||||
### 1. 自动同步逻辑
|
||||
|
||||
@@ -15,7 +15,7 @@
|
||||
- 必须确保 `bindPort`（frpc 连接端口，默认 `7000`）可被公网/内网客户端访问。
|
||||
- 必须确保 `vhostHTTPPort`（HTTP Vhost 端口，默认 `8080`）处于空闲状态，Agent 将在此端口上与 frps 进行流量传递。
|
||||
3. **软件依赖**（仅限宿主机直接部署）：
|
||||
- 本地需有可执行的 `frps` 二进制文件（建议版本为 `v0.61.0+` 或最新稳定版 `v0.69.0`），或通过参数显式指定路径。
|
||||
- 本地需有可执行的 `frps` 二进制文件，或通过参数显式指定路径。
|
||||
|
||||
---
|
||||
|
||||
@@ -40,9 +40,9 @@
|
||||
|
||||
---
|
||||
|
||||
## Docker 运行（推荐）
|
||||
## Docker 运行）
|
||||
|
||||
Docker 运行是 TunnelRelay 节点最便捷的部署方案。官方镜像内置了 `openflare-relay` 控制器与 `frps v0.69.0` 运行时，开箱即用。
|
||||
Docker 运行是 TunnelRelay 节点最便捷的部署方案。官方镜像内置了 `openflare-relay` 控制器与 `frps` 运行时，开箱即用。
|
||||
|
||||
```bash
|
||||
docker pull ghcr.io/rain-kl/openflare-relay:latest
|
||||
@@ -67,39 +67,6 @@ docker run -d --name openflare-relay --restart unless-stopped \
|
||||
|
||||
---
|
||||
|
||||
## 宿主机手动运行
|
||||
|
||||
如果您倾向于在物理机或虚拟机上直接运行：
|
||||
|
||||
### 1. 编译二进制
|
||||
|
||||
```bash
|
||||
go build -o bin/openflare-relay ./cmd/relay
|
||||
```
|
||||
|
||||
### 2. 准备 `relay.json`
|
||||
|
||||
在程序同级目录下创建 `relay.json` 配置文件：
|
||||
|
||||
```json
|
||||
{
|
||||
"server_url": "http://127.0.0.1:3000",
|
||||
"agent_token": "your-relay-node-agent-token",
|
||||
"frps_path": "/usr/local/bin/frps",
|
||||
"data_dir": "./data",
|
||||
"heartbeat_interval": "10s",
|
||||
"request_timeout": "10s"
|
||||
}
|
||||
```
|
||||
|
||||
### 3. 运行服务
|
||||
|
||||
```bash
|
||||
export LOG_LEVEL='info'
|
||||
./openflare-relay -config ./relay.json
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 启动与验证
|
||||
|
||||
@@ -110,11 +77,6 @@ export LOG_LEVEL='info'
|
||||
docker logs -f openflare-relay
|
||||
```
|
||||
|
||||
如果是在 Linux 上通过 Systemd 托管的，可执行：
|
||||
```bash
|
||||
journalctl -u openflare-relay -f
|
||||
```
|
||||
|
||||
### 2. 验证运行状态
|
||||
|
||||
启动成功后，Relay 将进行以下工作：
|
||||
|
||||
+13
-151
@@ -6,7 +6,8 @@ OpenFlare Server 是 Gin + GORM 单体控制面，负责管理端 UI、管理 AP
|
||||
|
||||
> [!IMPORTANT]
|
||||
> **关于外部依赖**：
|
||||
> OpenFlare 系统内建了对后台异步任务（Asynq 框架）及海量节点日志分析与度量指标（观测面板）的支持。因此，**无论采用何种部署模式，系统都必须依赖 Redis（或 Valkey）与 ClickHouse 的运行**。各个部署方案的主要差异在于主关系型数据库的选择（SQLite vs PostgreSQL）以及是否启用链路追踪服务（Jaeger）。
|
||||
> OpenFlare 系统内建了对后台异步任务（Asynq 框架）的支持。因此，**无论采用何种部署模式，系统都必须依赖 Redis（或 Valkey）**。各个部署方案的主要差异在于主关系型数据库的选择（SQLite vs PostgreSQL）以及是否启用链路追踪服务（Jaeger）。
|
||||
> 若业务流量过大, 建议使用 ClickHouse 存储日志。
|
||||
|
||||
> [!TIP]
|
||||
> **ClickHouse 服务端性能配置（推荐挂载）**
|
||||
@@ -37,11 +38,11 @@ volumes:
|
||||
|
||||
使用 Docker 部署可以免去本地配置 Go 与 Node.js 前端构建环境的麻烦。根据你的服务器硬件配置及业务需求，你可以选择以下三种方案之一：
|
||||
|
||||
### 1. 快速启动 (SQLite + Redis + ClickHouse)
|
||||
### 1. 快速启动 (SQLite + Redis)
|
||||
|
||||
> **适用场景**：测试体验、轻量化单机部署。
|
||||
>
|
||||
> **特点**：主关系型数据库使用内建的 SQLite 文件
|
||||
> **特点**：主关系型数据库使用 SQLite
|
||||
|
||||
创建 `docker-compose.yaml` 文件：
|
||||
|
||||
@@ -70,8 +71,6 @@ services:
|
||||
depends_on:
|
||||
redis:
|
||||
condition: service_healthy
|
||||
clickhouse:
|
||||
condition: service_healthy
|
||||
|
||||
redis:
|
||||
image: valkey/valkey:8.0-alpine
|
||||
@@ -84,47 +83,13 @@ services:
|
||||
interval: 10s
|
||||
timeout: 5s
|
||||
retries: 5
|
||||
|
||||
clickhouse:
|
||||
image: clickhouse/clickhouse-server:25.3-alpine
|
||||
restart: unless-stopped
|
||||
environment:
|
||||
CLICKHOUSE_DB: openflare
|
||||
CLICKHOUSE_USER: default
|
||||
CLICKHOUSE_PASSWORD: 123456
|
||||
CLICKHOUSE_DEFAULT_ACCESS_MANAGEMENT: 1
|
||||
TZ: Asia/Shanghai
|
||||
ulimits:
|
||||
nofile:
|
||||
soft: 262144
|
||||
hard: 262144
|
||||
volumes:
|
||||
- ./data/clickhouse_data:/var/lib/clickhouse
|
||||
- ./config/clickhouse/performance.xml:/etc/clickhouse-server/config.d/performance.xml:ro
|
||||
healthcheck:
|
||||
test: ["CMD", "clickhouse-client", "--user", "default", "--password", "123456", "--query", "SELECT 1"]
|
||||
interval: 10s
|
||||
timeout: 5s
|
||||
retries: 5
|
||||
start_period: 15s
|
||||
```
|
||||
|
||||
运行启动命令：
|
||||
|
||||
```bash
|
||||
mkdir -p ./config/clickhouse
|
||||
curl -fsSL -o ./config/clickhouse/performance.xml \
|
||||
https://raw.githubusercontent.com/Rain-kl/OpenFlare/refs/heads/main/config/clickhouse/performance.xml
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 2. 生产推荐 (PostgreSQL + Redis + ClickHouse)
|
||||
### 2. 小流量业务场景 (PostgreSQL + Redis)
|
||||
|
||||
> **适用场景**：生产环境、多节点集群管理、高并发高可用要求。
|
||||
>
|
||||
> **特点**：完全分层架构。启用专用的 PostgreSQL 服务作为主关系数据库，Redis 负责高并发分布式锁、会话缓存与异步队列，ClickHouse 承载海量日志异步 Flush 与观测指标。
|
||||
> **适用场景**：生产环境、业务流量中小, PostgreSQL 不会成为日志记录的瓶颈。
|
||||
|
||||
创建 `docker-compose.yaml` 文件：
|
||||
|
||||
@@ -145,8 +110,6 @@ services:
|
||||
condition: service_healthy
|
||||
redis:
|
||||
condition: service_healthy
|
||||
clickhouse:
|
||||
condition: service_healthy
|
||||
|
||||
postgres:
|
||||
image: postgres:17-alpine
|
||||
@@ -176,45 +139,18 @@ services:
|
||||
retries: 5
|
||||
start_period: 5s
|
||||
|
||||
clickhouse:
|
||||
image: clickhouse/clickhouse-server:25.3-alpine
|
||||
restart: unless-stopped
|
||||
environment:
|
||||
CLICKHOUSE_DB: ${CLICKHOUSE_NAME:-openflare}
|
||||
CLICKHOUSE_USER: ${CLICKHOUSE_USERNAME:-default}
|
||||
CLICKHOUSE_PASSWORD: ${CLICKHOUSE_PASSWORD:-replace-with-clickhouse-password}
|
||||
CLICKHOUSE_DEFAULT_ACCESS_MANAGEMENT: 1
|
||||
TZ: ${TZ:-Asia/Shanghai}
|
||||
ulimits:
|
||||
nofile:
|
||||
soft: 262144
|
||||
hard: 262144
|
||||
volumes:
|
||||
- openflare_clickhouse_data:/var/lib/clickhouse
|
||||
- ./config/clickhouse/performance.xml:/etc/clickhouse-server/config.d/performance.xml:ro
|
||||
healthcheck:
|
||||
test: ["CMD", "clickhouse-client", "--user", "${CLICKHOUSE_USERNAME:-default}", "--password", "${CLICKHOUSE_PASSWORD:-replace-with-clickhouse-password}", "--query", "SELECT 1"]
|
||||
interval: 10s
|
||||
timeout: 5s
|
||||
retries: 5
|
||||
start_period: 15s
|
||||
|
||||
volumes:
|
||||
openflare_uploads:
|
||||
openflare_postgres_data:
|
||||
openflare_redis_data:
|
||||
openflare_clickhouse_data:
|
||||
```
|
||||
|
||||
创建对应的 `.env` 文件来配置系统环境变量（可复制并修改根目录下的 `.env.example`）：
|
||||
|
||||
```bash
|
||||
mkdir -p ./config/clickhouse
|
||||
curl -fsSL -o ./config/clickhouse/performance.xml \
|
||||
https://raw.githubusercontent.com/Rain-kl/OpenFlare/refs/heads/main/config/clickhouse/performance.xml
|
||||
curl -o .env.example https://raw.githubusercontent.com/Rain-kl/OpenFlare/refs/heads/main/.env.example
|
||||
cp .env.example .env
|
||||
# 编辑 .env 文件，填入对应的数据库、Redis、ClickHouse 连接地址、密码与 APP_SESSION_SECRET
|
||||
# 编辑 .env 文件，填入对应的数据库、Redis、密码与 APP_SESSION_SECRET
|
||||
|
||||
docker compose up -d
|
||||
```
|
||||
@@ -223,9 +159,9 @@ docker compose up -d
|
||||
|
||||
### 3. 进阶版 (含 Jaeger 链路追踪的完整编排)
|
||||
|
||||
> **适用场景**：开发者调试、系统深度性能诊断、高级可观测性追溯。
|
||||
> **适用场景**：大流量场景, 需要进行链路性能指标追踪。
|
||||
>
|
||||
> **特点**：在“生产推荐”全家桶的基础上，联动拉起 Jaeger 作为 OpenTelemetry (OTel) 链路追踪的后端，收集 Server 运行时各个 API 请求的 Span Trace 信息。
|
||||
> **特点**：在“生产推荐”全家桶的基础上，使用 ClickHouse 存储日志, 联动 Jaeger 作为 OpenTelemetry (OTel) 链路追踪的后端。
|
||||
|
||||
创建 `docker-compose.yaml` 文件：
|
||||
|
||||
@@ -340,64 +276,6 @@ docker compose up -d
|
||||
|
||||
---
|
||||
|
||||
## 方式二：本地部署 (源码/二进制启动)
|
||||
|
||||
如果你不希望使用 Docker，也可以直接在本地或虚拟机上从源码构建和运行 Server。由于后台异步任务和可观测指标分析为系统核心防线，**本地部署时依然需要连接外部 Redis 与 ClickHouse 实例**。
|
||||
|
||||
### 前置条件
|
||||
|
||||
| 项目 | 要求 |
|
||||
| --- | --- |
|
||||
| Go | `1.25+` |
|
||||
| Node.js | `18+` |
|
||||
| pnpm | 推荐通过 `corepack enable` 使用项目声明的 pnpm |
|
||||
| 外部服务 | 必须在本地或远端运行 Redis (Valkey) 和 ClickHouse 实例；ClickHouse 建议挂载仓库提供的 `performance.xml`（见上文「ClickHouse 服务端性能配置」） |
|
||||
|
||||
### 1. 构建管理端前端
|
||||
|
||||
Go Server 运行时需要嵌入前端静态资源。编译 Go 二进制前需要先构建前端静态产物并输出到 Go 服务目录：
|
||||
|
||||
```bash
|
||||
cd frontend
|
||||
corepack enable
|
||||
pnpm install
|
||||
pnpm build:embed
|
||||
cd ..
|
||||
```
|
||||
|
||||
> **常用前端代码检查命令**：
|
||||
> * `pnpm lint`
|
||||
> * `pnpm typecheck`
|
||||
|
||||
### 2. 使用 SQLite 启动
|
||||
|
||||
关系数据库存储在本地 SQLite 文件，但依然需要提供 Redis 和 ClickHouse 连接配置：
|
||||
|
||||
```bash
|
||||
cp config.example.yaml config.yaml
|
||||
# 编辑 config.yaml：
|
||||
# 1. 设置 app.session_secret 为一个随机的长字符串
|
||||
# 2. 将 database.enabled 设为 false 以启用内置 SQLite
|
||||
# 3. 将 redis.addrs 与 clickhouse.hosts 修改为你的本地/局域网服务连接信息
|
||||
|
||||
# 启动 Server（默认融合模式）
|
||||
go run main.go all
|
||||
```
|
||||
|
||||
### 3. 使用 PostgreSQL 启动
|
||||
|
||||
```bash
|
||||
cp config.example.yaml config.yaml
|
||||
# 编辑 config.yaml：
|
||||
# 1. 设置 app.session_secret
|
||||
# 2. 将 database.enabled 设为 true，并完整设置 database.*、redis.*、clickhouse.* 字段连接参数
|
||||
|
||||
# 启动 Server（默认融合模式）
|
||||
go run main.go all
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 首次登录
|
||||
|
||||
Server 默认监听 `3000` 端口，启动成功后可以使用浏览器访问：`http://localhost:3000`。
|
||||
@@ -413,28 +291,12 @@ Server 默认监听 `3000` 端口，启动成功后可以使用浏览器访问
|
||||
|
||||
---
|
||||
|
||||
## 常用运维指南
|
||||
|
||||
### 1. 命令行子服务分进程启动
|
||||
## 分布式部署
|
||||
|
||||
在大型生产部署中，你可以选择将 Server 按职责拆分为多个进程运行：
|
||||
|
||||
```bash
|
||||
go run main.go api # 仅启动管理端与节点通信的 API 服务
|
||||
go run main.go worker # 仅启动后台任务的 Worker 服务
|
||||
go run main.go scheduler # 仅启动定时任务的 Scheduler 服务
|
||||
go run main.go all # 融合模式（在一进程内运行上述所有服务，默认）
|
||||
```
|
||||
|
||||
### 2. 状态验证
|
||||
|
||||
```bash
|
||||
# 验证编译是否通过
|
||||
go build ./...
|
||||
|
||||
# 运行内部单元测试
|
||||
go test ./internal/apps/openflare/... -count=1
|
||||
|
||||
# 检查服务健康状态
|
||||
curl http://127.0.0.1:3000/api/v1/d/status
|
||||
go run main.go api # 仅启动管理端与节点通信的 API 服务
|
||||
go run main.go worker # 仅启动后台任务的 Worker 服务
|
||||
go run main.go scheduler # 仅启动定时任务的 Scheduler 服务
|
||||
```
|
||||
|
||||
+108
-168
@@ -1024,7 +1024,7 @@ const docTemplate = `{
|
||||
"SessionCookie": []
|
||||
}
|
||||
],
|
||||
"description": "分页并按照用户、接口路径、时间范围等维度检索 ClickHouse 用户访问日志列表（需要管理员权限，ClickHouse 未启用时报错）",
|
||||
"description": "分页并按照用户、接口路径、时间范围等维度检索用户访问日志列表（需要管理员权限，日志存储未启用时报错）",
|
||||
"produces": [
|
||||
"application/json"
|
||||
],
|
||||
@@ -1092,7 +1092,7 @@ const docTemplate = `{
|
||||
}
|
||||
},
|
||||
"400": {
|
||||
"description": "ClickHouse 未启用或参数错误",
|
||||
"description": "日志存储未启用或参数错误",
|
||||
"schema": {
|
||||
"$ref": "#/definitions/response.Any"
|
||||
}
|
||||
@@ -1119,7 +1119,7 @@ const docTemplate = `{
|
||||
"SessionCookie": []
|
||||
}
|
||||
],
|
||||
"description": "聚合统计最近 7 天的每日访问趋势、浏览器分布以及前 10 名最活跃用户排行（需要管理员权限，ClickHouse 未启用时报错）",
|
||||
"description": "聚合统计最近 7 天的每日访问趋势、浏览器分布以及前 10 名最活跃用户排行（需要管理员权限，日志存储未启用时报错）",
|
||||
"produces": [
|
||||
"application/json"
|
||||
],
|
||||
@@ -1147,7 +1147,7 @@ const docTemplate = `{
|
||||
}
|
||||
},
|
||||
"400": {
|
||||
"description": "ClickHouse 未启用",
|
||||
"description": "日志存储未启用",
|
||||
"schema": {
|
||||
"$ref": "#/definitions/response.Any"
|
||||
}
|
||||
@@ -1877,21 +1877,21 @@ const docTemplate = `{
|
||||
}
|
||||
}
|
||||
},
|
||||
"/api/v1/admin/status/clickhouse": {
|
||||
"/api/v1/admin/status/log-database": {
|
||||
"get": {
|
||||
"security": [
|
||||
{
|
||||
"SessionCookie": []
|
||||
}
|
||||
],
|
||||
"description": "返回 ClickHouse parts、mutation、async_insert 队列及进程内 batch writer 指标，需要管理员权限",
|
||||
"description": "返回当前日志主库、迁移状态、各库保留天数与合法迁移目标，需要管理员权限",
|
||||
"produces": [
|
||||
"application/json"
|
||||
],
|
||||
"tags": [
|
||||
"admin"
|
||||
],
|
||||
"summary": "获取 ClickHouse 运行指标",
|
||||
"summary": "获取日志数据库状态",
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "获取成功",
|
||||
@@ -1904,19 +1904,13 @@ const docTemplate = `{
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"data": {
|
||||
"$ref": "#/definitions/analytics.ClickHouseOperationalStats"
|
||||
"$ref": "#/definitions/status.LogDatabaseStatus"
|
||||
}
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
},
|
||||
"400": {
|
||||
"description": "ClickHouse 未启用",
|
||||
"schema": {
|
||||
"$ref": "#/definitions/response.Any"
|
||||
}
|
||||
},
|
||||
"401": {
|
||||
"description": "未登录",
|
||||
"schema": {
|
||||
@@ -2393,6 +2387,18 @@ const docTemplate = `{
|
||||
"name": "task_type",
|
||||
"in": "query"
|
||||
},
|
||||
{
|
||||
"type": "string",
|
||||
"description": "任务类型前缀筛选（与 task_type / task_types 互斥，精确类型优先）",
|
||||
"name": "task_type_prefix",
|
||||
"in": "query"
|
||||
},
|
||||
{
|
||||
"type": "string",
|
||||
"description": "逗号分隔的精确任务类型列表（IN 筛选，优先于前缀）",
|
||||
"name": "task_types",
|
||||
"in": "query"
|
||||
},
|
||||
{
|
||||
"type": "integer",
|
||||
"default": 1,
|
||||
@@ -4803,7 +4809,7 @@ const docTemplate = `{
|
||||
"SessionCookie": []
|
||||
}
|
||||
],
|
||||
"description": "分页返回 OpenFlare 访问日志，支持按节点、IP、主机与路径筛选，需要管理员权限",
|
||||
"description": "分页返回 OpenFlare 访问日志，支持按节点、IP、主机、路径与状态码筛选，需要管理员权限",
|
||||
"produces": [
|
||||
"application/json"
|
||||
],
|
||||
@@ -4836,6 +4842,24 @@ const docTemplate = `{
|
||||
"name": "path",
|
||||
"in": "query"
|
||||
},
|
||||
{
|
||||
"type": "integer",
|
||||
"description": "HTTP 状态码（100-599）",
|
||||
"name": "status_code",
|
||||
"in": "query"
|
||||
},
|
||||
{
|
||||
"type": "string",
|
||||
"description": "起始时间（RFC3339，需与 until 成对提供）",
|
||||
"name": "since",
|
||||
"in": "query"
|
||||
},
|
||||
{
|
||||
"type": "string",
|
||||
"description": "结束时间（RFC3339，需与 since 成对提供）",
|
||||
"name": "until",
|
||||
"in": "query"
|
||||
},
|
||||
{
|
||||
"type": "integer",
|
||||
"description": "页码",
|
||||
@@ -8305,80 +8329,6 @@ const docTemplate = `{
|
||||
}
|
||||
}
|
||||
},
|
||||
"/api/v1/d/option/database/cleanup": {
|
||||
"post": {
|
||||
"security": [
|
||||
{
|
||||
"SessionCookie": []
|
||||
}
|
||||
],
|
||||
"description": "按目标与保留天数清理可观测性相关数据表，需要管理员权限",
|
||||
"consumes": [
|
||||
"application/json"
|
||||
],
|
||||
"produces": [
|
||||
"application/json"
|
||||
],
|
||||
"tags": [
|
||||
"openflare-option"
|
||||
],
|
||||
"summary": "清理可观测性数据库",
|
||||
"parameters": [
|
||||
{
|
||||
"description": "清理参数",
|
||||
"name": "request",
|
||||
"in": "body",
|
||||
"schema": {
|
||||
"$ref": "#/definitions/option.databaseCleanupInput"
|
||||
}
|
||||
}
|
||||
],
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "清理结果",
|
||||
"schema": {
|
||||
"allOf": [
|
||||
{
|
||||
"$ref": "#/definitions/response.Any"
|
||||
},
|
||||
{
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"data": {
|
||||
"$ref": "#/definitions/option.databaseCleanupResult"
|
||||
}
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
},
|
||||
"400": {
|
||||
"description": "参数错误",
|
||||
"schema": {
|
||||
"$ref": "#/definitions/response.Any"
|
||||
}
|
||||
},
|
||||
"401": {
|
||||
"description": "未登录",
|
||||
"schema": {
|
||||
"$ref": "#/definitions/response.Any"
|
||||
}
|
||||
},
|
||||
"404": {
|
||||
"description": "无权限或不存在",
|
||||
"schema": {
|
||||
"$ref": "#/definitions/response.Any"
|
||||
}
|
||||
},
|
||||
"500": {
|
||||
"description": "内部错误",
|
||||
"schema": {
|
||||
"$ref": "#/definitions/response.Any"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"/api/v1/d/option/geoip/lookup": {
|
||||
"post": {
|
||||
"security": [
|
||||
@@ -14906,33 +14856,26 @@ const docTemplate = `{
|
||||
}
|
||||
}
|
||||
},
|
||||
"analytics.ClickHouseOperationalStats": {
|
||||
"analytics.BatchWriterStats": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"active_parts": {
|
||||
"cap": {
|
||||
"type": "integer"
|
||||
},
|
||||
"async_insert_bytes": {
|
||||
"depth": {
|
||||
"type": "integer"
|
||||
},
|
||||
"async_insert_queue": {
|
||||
"drops": {
|
||||
"type": "integer"
|
||||
},
|
||||
"batch_writers": {
|
||||
"description": "BatchWriters reports in-process queue depth/drops/flush errors for CH writers.",
|
||||
"type": "array",
|
||||
"items": {
|
||||
"$ref": "#/definitions/batchwriter.Stats"
|
||||
}
|
||||
"flush_errors": {
|
||||
"type": "integer"
|
||||
},
|
||||
"database": {
|
||||
"name": {
|
||||
"type": "string"
|
||||
},
|
||||
"pending_mutations": {
|
||||
"type": "integer"
|
||||
},
|
||||
"total_rows": {
|
||||
"type": "integer"
|
||||
"running": {
|
||||
"type": "boolean"
|
||||
}
|
||||
}
|
||||
},
|
||||
@@ -15024,29 +14967,6 @@ const docTemplate = `{
|
||||
}
|
||||
}
|
||||
},
|
||||
"batchwriter.Stats": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"cap": {
|
||||
"type": "integer"
|
||||
},
|
||||
"depth": {
|
||||
"type": "integer"
|
||||
},
|
||||
"drops": {
|
||||
"type": "integer"
|
||||
},
|
||||
"flush_errors": {
|
||||
"type": "integer"
|
||||
},
|
||||
"name": {
|
||||
"type": "string"
|
||||
},
|
||||
"running": {
|
||||
"type": "boolean"
|
||||
}
|
||||
}
|
||||
},
|
||||
"cache.updateCacheConfigRequest": {
|
||||
"type": "object",
|
||||
"required": [
|
||||
@@ -15105,6 +15025,9 @@ const docTemplate = `{
|
||||
"id": {
|
||||
"type": "integer"
|
||||
},
|
||||
"zone_domain": {
|
||||
"type": "string"
|
||||
},
|
||||
"zone_id": {
|
||||
"type": "integer"
|
||||
}
|
||||
@@ -15826,6 +15749,36 @@ const docTemplate = `{
|
||||
}
|
||||
}
|
||||
},
|
||||
"github_com_Rain-kl_Wavelet_internal_model_analytics.ClickHouseOperationalStats": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"active_parts": {
|
||||
"type": "integer"
|
||||
},
|
||||
"async_insert_bytes": {
|
||||
"type": "integer"
|
||||
},
|
||||
"async_insert_queue": {
|
||||
"type": "integer"
|
||||
},
|
||||
"batch_writers": {
|
||||
"description": "BatchWriters reports in-process queue depth/drops/flush errors for CH writers.",
|
||||
"type": "array",
|
||||
"items": {
|
||||
"$ref": "#/definitions/analytics.BatchWriterStats"
|
||||
}
|
||||
},
|
||||
"database": {
|
||||
"type": "string"
|
||||
},
|
||||
"pending_mutations": {
|
||||
"type": "integer"
|
||||
},
|
||||
"total_rows": {
|
||||
"type": "integer"
|
||||
}
|
||||
}
|
||||
},
|
||||
"github_com_Rain-kl_Wavelet_pkg_protocol.ActiveConfigMeta": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
@@ -18481,46 +18434,6 @@ const docTemplate = `{
|
||||
}
|
||||
}
|
||||
},
|
||||
"option.databaseCleanupInput": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"retention_days": {
|
||||
"type": "integer"
|
||||
},
|
||||
"target": {
|
||||
"type": "string"
|
||||
}
|
||||
}
|
||||
},
|
||||
"option.databaseCleanupResult": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"cleanup_mode": {
|
||||
"type": "string"
|
||||
},
|
||||
"delete_all": {
|
||||
"type": "boolean"
|
||||
},
|
||||
"deleted_count": {
|
||||
"type": "integer"
|
||||
},
|
||||
"eligible_count": {
|
||||
"type": "integer"
|
||||
},
|
||||
"retention_days": {
|
||||
"type": "integer"
|
||||
},
|
||||
"table_ttl_days": {
|
||||
"type": "integer"
|
||||
},
|
||||
"target": {
|
||||
"type": "string"
|
||||
},
|
||||
"target_label": {
|
||||
"type": "string"
|
||||
}
|
||||
}
|
||||
},
|
||||
"option.geoIPLookupRequest": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
@@ -19859,6 +19772,33 @@ const docTemplate = `{
|
||||
}
|
||||
}
|
||||
},
|
||||
"status.LogDatabaseStatus": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"active_database": {
|
||||
"type": "string"
|
||||
},
|
||||
"available_targets": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "string"
|
||||
}
|
||||
},
|
||||
"clickhouse": {
|
||||
"$ref": "#/definitions/github_com_Rain-kl_Wavelet_internal_model_analytics.ClickHouseOperationalStats"
|
||||
},
|
||||
"migration": {
|
||||
"description": "idle | migrating",
|
||||
"type": "string"
|
||||
},
|
||||
"retention_days": {
|
||||
"type": "object",
|
||||
"additionalProperties": {
|
||||
"type": "integer"
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"status.SystemStatusResponse": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
|
||||
+13
-42
@@ -14,12 +14,12 @@ Agent 统一通过 OpenResty 二进制控制运行时。本地部署需要节点
|
||||
|
||||
## 环境要求
|
||||
|
||||
| 项目 | 要求 |
|
||||
| --- | --- |
|
||||
| Docker / Docker Compose | 用于启动 Server 及其依赖的 PostgreSQL、Redis 和 ClickHouse 容器；如采用 Docker Agent，也用于运行 Agent |
|
||||
| OpenResty | 本地安装 Agent 时需要可执行 `openresty`，或在安装脚本中指定路径 |
|
||||
| 可访问端口 | Server 默认监听 `3000`，Agent 节点需要能访问 Server 地址 |
|
||||
| 浏览器 | 用于访问管理端 |
|
||||
| 项目 | 要求 |
|
||||
| --- |------------------------------------------------------------------|
|
||||
| Docker / Docker Compose | 用于启动 Server 及其依赖的 PostgreSQL、Valkey；如采用 Docker Agent，也用于运行 Agent |
|
||||
| OpenResty | 本地安装 Agent 时需要可执行 `openresty`，或在安装脚本中指定路径 |
|
||||
| 可访问端口 | Server 默认监听 `3000`，Agent 节点需要能访问 Server 地址 |
|
||||
| 浏览器 | 用于访问管理端 |
|
||||
|
||||
- **Docker**：`20.10.0+`
|
||||
- **Docker Compose**：`2.0.0+`
|
||||
@@ -28,15 +28,7 @@ Agent 统一通过 OpenResty 二进制控制运行时。本地部署需要节点
|
||||
|
||||
## 1. 启动 Server
|
||||
|
||||
为了保证异步任务队列（Asynq 框架）及可观测流量看板功能完整运行，快速开始推荐采用 **PostgreSQL + Redis + ClickHouse** 经典单机版编排。
|
||||
|
||||
先拉取 ClickHouse 服务端性能配置到 `./config/clickhouse`，并以单文件方式挂载：
|
||||
|
||||
```bash
|
||||
mkdir -p ./config/clickhouse
|
||||
curl -fsSL -o ./config/clickhouse/performance.xml \
|
||||
https://raw.githubusercontent.com/Rain-kl/OpenFlare/refs/heads/main/config/clickhouse/performance.xml
|
||||
```
|
||||
快速开始推荐采用 **PostgreSQL + Redis ** 标准部署方案。
|
||||
|
||||
在空目录中创建 `docker-compose.yaml`：
|
||||
|
||||
@@ -63,15 +55,11 @@ services:
|
||||
DB_NAME: "${DB_NAME:-openflare}"
|
||||
REDIS_ENABLED: "true"
|
||||
REDIS_ADDR: "redis:6379"
|
||||
CLICKHOUSE_ENABLED: "true"
|
||||
CLICKHOUSE_HOST: "clickhouse:9000"
|
||||
depends_on:
|
||||
postgres:
|
||||
condition: service_healthy
|
||||
redis:
|
||||
condition: service_healthy
|
||||
clickhouse:
|
||||
condition: service_healthy
|
||||
|
||||
postgres:
|
||||
image: postgres:17-alpine
|
||||
@@ -100,34 +88,11 @@ services:
|
||||
timeout: 5s
|
||||
retries: 5
|
||||
|
||||
clickhouse:
|
||||
image: clickhouse/clickhouse-server:25.3-alpine
|
||||
restart: unless-stopped
|
||||
environment:
|
||||
CLICKHOUSE_DB: openflare
|
||||
CLICKHOUSE_USER: default
|
||||
CLICKHOUSE_PASSWORD: ${CLICKHOUSE_PASSWORD:-replace-with-clickhouse-password}
|
||||
CLICKHOUSE_DEFAULT_ACCESS_MANAGEMENT: 1
|
||||
TZ: Asia/Shanghai
|
||||
ulimits:
|
||||
nofile:
|
||||
soft: 262144
|
||||
hard: 262144
|
||||
volumes:
|
||||
- openflare_clickhouse_data:/var/lib/clickhouse
|
||||
- ./config/clickhouse/performance.xml:/etc/clickhouse-server/config.d/performance.xml:ro
|
||||
healthcheck:
|
||||
test: ["CMD", "clickhouse-client", "--user", "default", "--password", "${CLICKHOUSE_PASSWORD:-replace-with-clickhouse-password}", "--query", "SELECT 1"]
|
||||
interval: 10s
|
||||
timeout: 5s
|
||||
retries: 5
|
||||
start_period: 15s
|
||||
|
||||
volumes:
|
||||
openflare_uploads:
|
||||
openflare_postgres_data:
|
||||
openflare_redis_data:
|
||||
openflare_clickhouse_data:
|
||||
```
|
||||
|
||||
启动服务：
|
||||
@@ -158,6 +123,12 @@ http://localhost:3000
|
||||
> [!WARNING]
|
||||
> 为了你的系统安全，首次登录后请立即修改默认密码。
|
||||
|
||||
如果忘记密码并且没有配置找回密码渠道, 可以使用命令进行重置
|
||||
|
||||
```bash
|
||||
go run main.go reset-paswd # 重置管理员密码
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. 准备 Agent Token
|
||||
|
||||
@@ -8,7 +8,7 @@ OpenFlare WAF 使用可视化有向无环图编排规则。新建规则时只填
|
||||
- **通过**：结束当前规则；若路由仍有后续规则则继续执行。
|
||||
- **阻止**：立即按配置的状态码和 HTML 响应终止请求。
|
||||
- **IP 匹配**：配置 IP、CIDR 或 IP 组，分别连接 `true`、`false`。
|
||||
- **地域匹配**：按国家或 ISO 3166-2 一级行政区代码分支；国家列表同时显示中文名称与代码，行政区可按国家名、行政区名或代码搜索。Country 与 City MMDB 缺失时由 Agent 从程序内嵌数据库初始化，并按配置周期更新。City MMDB 不可用时按未匹配处理。
|
||||
- **地域匹配**：按国家或 ISO 3166-2 一级行政区代码分支；国家列表同时显示中文名称与代码，行政区可按国家名、行政区名或代码搜索。Country 与 City MMDB 由磁盘文件提供（Docker 镜像会 COPY 到默认路径；裸二进制首次启动时按配置 URL 下载），并按配置周期更新。City MMDB 不可用时按未匹配处理。
|
||||
- **PoW**：未完成挑战时接管请求，验证通过后沿 `next` 继续。
|
||||
|
||||
服务端会拒绝循环、悬空出口、不可达节点、重复端口连接和无效配置。保存时携带页面加载得到的 `revision`；发生 409 冲突时应重新加载，避免覆盖他人修改。
|
||||
|
||||
@@ -105,7 +105,7 @@ Server 的所有核心基础配置定义在 `config.yaml` 中，且均支持环
|
||||
|
||||
| 配置文件 YAML 路径 | 对应覆盖环境变量 | 作用说明 | 默认值 |
|
||||
| --- | --- | --- | --- |
|
||||
| `clickhouse.enabled` | `CLICKHOUSE_ENABLED` | 是否启用 ClickHouse。**系统节点指标与访问日志在此进行海量写入** | `true` |
|
||||
| `clickhouse.enabled` | `CLICKHOUSE_ENABLED` | 是否启用 ClickHouse。**系统节点指标与访问日志在此进行海量写入**。默认关闭：缺失本配置项或为 `false` 时不启用，日志/指标由主库承担；显式 `true` 或设置 `CLICKHOUSE_HOST` 时启用 | `false` |
|
||||
| `clickhouse.hosts` | `CLICKHOUSE_HOST` | ClickHouse 集群连接地址数组（环境变量仅设置单地址） | `["127.0.0.1:9000"]` |
|
||||
| `clickhouse.username` | `CLICKHOUSE_USERNAME` | ClickHouse 账号用户名 | `default` |
|
||||
| `clickhouse.password` | `CLICKHOUSE_PASSWORD` | ClickHouse 密码 | `replace-with-clickhouse-password` |
|
||||
@@ -197,8 +197,6 @@ Server 的所有核心基础配置定义在 `config.yaml` 中，且均支持环
|
||||
| `node_offline_threshold` | `int` | 在管理后台中判定节点失去心跳并标注为离线状态的无响应阈值（毫秒） | `60000` (60s) |
|
||||
| `agent_update_repo` | `string` | Agent 节点更新下载自身二进制的 Release 仓库源 | `Rain-kl/OpenFlare` |
|
||||
| `geoip_provider` | `string` | GeoIP 提供商，支持 `maxmind` 等，用于 WAF 防护时地域分析 | `ipinfo` |
|
||||
| `database_auto_cleanup_enabled` | `bool` | 是否在每天凌晨 3:00 自动清理过期观测历史日志（降低数据库空间） | `true` |
|
||||
| `database_auto_cleanup_retention_days` | `int` | 自动清理观测数据（访问日志、度量曲线、审计等）的默认保留天数 | `30` |
|
||||
|
||||
### 5. Uptime Kuma 监控联动同步
|
||||
| 配置键 (Key) | 数据类型 | 作用说明 | 默认值 |
|
||||
@@ -266,11 +264,27 @@ Server 的所有核心基础配置定义在 `config.yaml` 中，且均支持环
|
||||
| 配置键 (Key) | 数据类型 | 作用说明 | 默认值 |
|
||||
| --- | --- | --- | --- |
|
||||
| `origin_error_page_enabled` | `bool` | 是否启用全局源站错误页。开启后，源站或网关返回的匹配状态码由自定义/默认 HTML 替换，**HTTP 状态码保持原值**；关闭后不生成相关指令，恢复透传。修改后需发布配置版本生效 | `true` |
|
||||
| `origin_error_page_get_only` | `bool` | 是否仅对 **GET** 请求生效。开启后仅 GET 的匹配错误状态码返回自定义错误页；POST/PUT 等其它方法**透传源站响应**（原始状态码与响应体不变） | `false` |
|
||||
| `origin_error_page_status_codes` | `json` | 触发错误页的状态码标签 JSON 数组。支持单码（如 `522`）与闭区间（如 `500-599`）；单码与区间两端均须在 **400–599**，且 `lo ≤ hi`。启用时展开结果不能为空 | `["500-599"]` |
|
||||
| `origin_error_page_html` | `string` | 错误页自定义 HTML。空字符串表示使用内置 OpenFlare 默认模板（极简白底）；支持占位符 `{{status}}`（与 HTTP 状态码一致）、`{{host}}`（请求 Host）。最大 **256 KiB**（按字节）。勿嵌入不可信第三方脚本 | 空 |
|
||||
|
||||
---
|
||||
|
||||
### 8. 日志存储（Log Database）
|
||||
|
||||
日志存储解耦后的运行时配置：日志主库由「切换日志数据库」任务管理（内部/受保护 key，禁止管理员手动修改），访问日志保留天数按存储库分别在业务配置中设置；性能指标（CPU/内存/磁盘/网络）价值衰减快，按三库共用的独立短留存清理。
|
||||
|
||||
| 配置键 (Key) | 数据类型 | 作用说明 | 默认值 |
|
||||
| --- | --- | --- | --- |
|
||||
| `log_database` | `string` | 当前日志主库（`postgres` / `sqlite` / `clickhouse`）。**内部受保护 key**：仅「切换日志数据库」迁移任务写入，管理员不可手动创建/修改 | 随主库（PostgreSQL 启用时为 `postgres`，否则 `sqlite`；ClickHouse 启用时优先 `clickhouse`） |
|
||||
| `log_db_migration` | `string` | 日志迁移冻结标记（`migrating` 或空）。**内部受保护 key**：仅迁移任务写入，置位期间日志写入返回 503「日志数据库迁移中，暂不可写」 | 空 |
|
||||
| `log_retention_days_postgres` | `int` | PostgreSQL 日志库的访问日志过期清理保留天数（过期日志由系统垃圾清理每日任务删除） | `30` |
|
||||
| `log_retention_days_sqlite` | `int` | SQLite 日志库的访问日志过期清理保留天数 | `30` |
|
||||
| `log_retention_days_clickhouse` | `int` | ClickHouse 日志库的访问日志过期清理保留天数 | `30` |
|
||||
| `metric_retention_days` | `int` | 性能指标（CPU/内存/磁盘/网络）保留天数，三库共用独立短留存（不随访问日志保留配置） | `3` |
|
||||
|
||||
---
|
||||
|
||||
## 前端构建环境变量
|
||||
|
||||
| 环境变量 | 作用 | 默认值 |
|
||||
@@ -333,8 +347,8 @@ Server 的所有核心基础配置定义在 `config.yaml` 中，且均支持环
|
||||
| `mmdb_path` | WAF GeoIP mmdb 文件路径 | 否 | `data_dir/etc/openflare/GeoLite2-Country.mmdb` |
|
||||
| `city_mmdb_path` | WAF 地区匹配 City MMDB 文件路径 | 否 | `data_dir/etc/openflare/GeoLite2-City.mmdb` |
|
||||
| `mmdb_update_interval` | WAF GeoIP mmdb 更新间隔 | 否 | `86400000` 毫秒 (24h) |
|
||||
| `mmdb_download_url` | WAF GeoIP mmdb 周期更新地址 | 否 | GeoLite2 Country 更新地址；首次缺失时从程序内嵌数据库初始化 |
|
||||
| `city_mmdb_download_url` | WAF City MMDB 周期更新地址 | 否 | GeoLite2 City 更新地址；首次缺失时从程序内嵌数据库初始化 |
|
||||
| `mmdb_download_url` | WAF GeoIP mmdb 周期更新地址 | 否 | GeoLite2 Country 更新地址；磁盘文件缺失时首次下载（Docker 镜像已 COPY 默认路径文件） |
|
||||
| `city_mmdb_download_url` | WAF City MMDB 周期更新地址 | 否 | GeoLite2 City 更新地址；磁盘文件缺失时首次下载（Docker 镜像已 COPY 默认路径文件） |
|
||||
| `observability_buffer_path` | 观测补报缓冲文件路径 | 否 | `data_dir/var/lib/openflare/observability-buffer.json` |
|
||||
| `observability_replay_minutes` | 自动补传最近观测窗口分钟数 | 否 | `60` |
|
||||
| `state_path` | Agent 本地状态文件路径 | 否 | `data_dir/var/lib/openflare/agent-state.json` |
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,885 @@
|
||||
# Service Worker 离线兜底 Implementation Plan
|
||||
|
||||
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
||||
|
||||
**Goal:** 给平台所有启用 HTTPS 的网站（反代 + Pages）下发 Service Worker 离线兜底：域名被墙后浏览器从缓存吐出"联系站长"页，避免用户流失。全平台一键批量下发。
|
||||
|
||||
**Architecture:** 全局 Option（SystemConfig / OpenRestyConfig snapshot）驱动，与现有 origin error page 完全同模式。渲染层在 HTTPS server 块注入 SW 静态 location + 首页挑战拦截（真实浏览器 UA 且无 cookie 时返回含 `register('/sw.js')` 的挑战页），通过 SupportFile 下发 sw.js / offline.html，Agent 替换占位符落盘。前端「响应页面」模块两个 tab：错误页 / 联系页。
|
||||
|
||||
**Tech Stack:** Go 1.25+、Gin、GORM、PostgreSQL/SQLite goose 迁移、OpenResty/Lua、Next.js、TypeScript、shadcn/ui、TanStack Query。
|
||||
|
||||
## Global Constraints
|
||||
|
||||
- 遵循 AGENTS.md 分层：`apps → repository → model`，禁止 `model → repository`。
|
||||
- API 错误用 `response.Abort*`；Handler 不直接 `c.JSON`。
|
||||
- 渲染改动后：`make swagger`（本功能无新 API，跳过）；开发完成：`make code-check`；提交前：`make format`。
|
||||
- 代码/配置变更写入 `docs/changelog/index.md` 的 `[Unreleased]`（中文，用户可读）。
|
||||
- 配置 key 命名：小写 snake_case。测试临时目录只用 `t.TempDir()`。
|
||||
- 前端：`variant` + CSS 变量，业务 `className` 不硬编码颜色；根容器 `w-full`，外层 `py-6 px-1`；标题行 `flex items-center gap-2`。
|
||||
- 配置文件路径占位符统一追加到 `pkg/render/openresty/types.go` 的 const 块。
|
||||
- 迁移：PostgreSQL 与 SQLite 各一份 goose SQL（`goose/postgres/`、`goose/sqlite/`），见 `database-migration` skill。
|
||||
|
||||
---
|
||||
|
||||
### Task 1: 后端配置 key 与 Option 校验
|
||||
|
||||
**Files:**
|
||||
- Modify: `internal/model/system_configs.go:114-117`
|
||||
- Modify: `internal/apps/openflare/option/openresty_validators.go:19-65`
|
||||
- Modify: `internal/apps/openflare/option/openresty_validators.go:69-79`
|
||||
|
||||
**Interfaces:**
|
||||
- Produces: 常量 `model.ConfigKeySWOfflineEnabled`, `model.ConfigKeySWOfflineHTML`; 校验函数 `validateSWOfflineHTML`。
|
||||
|
||||
- [ ] **Step 1: 在 `system_configs.go` 追加 key 常量**
|
||||
|
||||
在 `ConfigKeyOriginErrorPageGetOnly`（第 117 行）后追加：
|
||||
|
||||
```go
|
||||
ConfigKeySWOfflineEnabled = "sw_offline_enabled" // 是否启用 Service Worker 离线兜底
|
||||
ConfigKeySWOfflineHTML = "sw_offline_html" // 离线联系页自定义 HTML（空则内置默认）
|
||||
```
|
||||
|
||||
- [ ] **Step 2: 注册 validator**
|
||||
|
||||
在 `openRestyOptionValidators` map（`openresty_validators.go` 第 61-64 行）后追加：
|
||||
|
||||
```go
|
||||
model.ConfigKeySWOfflineEnabled: validateBooleanOption,
|
||||
model.ConfigKeySWOfflineHTML: validateSWOfflineHTML,
|
||||
```
|
||||
|
||||
- [ ] **Step 3: 在 `validateOpenRestyOption` 增加 HTML 字节数特殊处理**
|
||||
|
||||
在第 69-79 行函数内，`if key == model.ConfigKeyOriginErrorPageHTML` 分支改为同时覆盖 SW HTML：
|
||||
|
||||
```go
|
||||
if key == model.ConfigKeyOriginErrorPageHTML || key == model.ConfigKeySWOfflineHTML {
|
||||
return validateOriginErrorPageHTML(key, value)
|
||||
}
|
||||
```
|
||||
|
||||
`validateOriginErrorPageHTML` 逻辑（非空、≤256 KiB）对两个 HTML 复用，无需新函数。
|
||||
|
||||
- [ ] **Step 4: 运行测试**
|
||||
|
||||
Run: `cd /Users/ryan/conductor/workspaces/OpenFlare/islamabad && go build ./... && go test ./internal/apps/openflare/option/...`
|
||||
Expected: PASS
|
||||
|
||||
- [ ] **Step 5: 提交**
|
||||
|
||||
```bash
|
||||
git add internal/model/system_configs.go internal/apps/openflare/option/openresty_validators.go
|
||||
git commit -m "feat(option): add sw offline config keys and validation"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Task 2: goose 迁移（PostgreSQL + SQLite）Seed 全局 Option
|
||||
|
||||
**Files:**
|
||||
- Create: `internal/infra/persistence/migrator/goose/postgres/<YYYYMMDD>NNN_add_sw_offline_options.sql`
|
||||
- Create: `internal/infra/persistence/migrator/goose/sqlite/<YYYYMMDD>NNN_add_sw_offline_options.sql`
|
||||
|
||||
**Interfaces:**
|
||||
- Consumes: Task 1 key 常量。
|
||||
- Produces: 数据库 seed 的 `sw_offline_enabled` / `sw_offline_html` 两行 `w_system_configs`。
|
||||
|
||||
- [ ] **Step 1: 确认迁移序号**
|
||||
|
||||
Run: `ls /Users/ryan/conductor/workspaces/OpenFlare/islamabad/internal/infra/persistence/migrator/goose/postgres/ | tail -3`
|
||||
取最新序号 +1（如 `202608080001`）。
|
||||
|
||||
- [ ] **Step 2: 创建 postgres 迁移**
|
||||
|
||||
创建 `goose/postgres/202608080001_add_sw_offline_options.sql`：
|
||||
|
||||
```sql
|
||||
-- +goose Up
|
||||
INSERT INTO w_system_configs (key, value, type, visibility, description, created_at, updated_at)
|
||||
VALUES
|
||||
('sw_offline_enabled', 'false', 'business', 0, '是否启用 Service Worker 离线兜底', CURRENT_TIMESTAMP, CURRENT_TIMESTAMP),
|
||||
('sw_offline_html', '', 'business', 0, '离线联系页自定义 HTML，空则使用内置默认', CURRENT_TIMESTAMP, CURRENT_TIMESTAMP)
|
||||
ON CONFLICT (key) DO NOTHING;
|
||||
|
||||
-- +goose Down
|
||||
DELETE FROM w_system_configs WHERE key IN (
|
||||
'sw_offline_enabled',
|
||||
'sw_offline_html'
|
||||
);
|
||||
```
|
||||
|
||||
- [ ] **Step 3: 创建 sqlite 迁移**
|
||||
|
||||
创建 `goose/sqlite/202608080001_add_sw_offline_options.sql`（内容与 postgres 相同）。
|
||||
|
||||
- [ ] **Step 4: 运行迁移测试**
|
||||
|
||||
Run: `go test ./internal/infra/persistence/migrator/...`
|
||||
Expected: PASS（数据库迁移冒烟通过）
|
||||
|
||||
- [ ] **Step 5: 提交**
|
||||
|
||||
```bash
|
||||
git add internal/infra/persistence/migrator/goose/postgres/202608080001_add_sw_offline_options.sql internal/infra/persistence/migrator/goose/sqlite/202608080001_add_sw_offline_options.sql
|
||||
git commit -m "feat(db): seed sw offline options"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Task 3: ConfigSnapshot 渲染类型字段
|
||||
|
||||
**Files:**
|
||||
- Modify: `pkg/render/openresty/types.go:20-26`
|
||||
- Modify: `pkg/render/openresty/types.go:318-323`（`ConfigSnapshot` 结构体）
|
||||
|
||||
**Interfaces:**
|
||||
- Produces: `ConfigSnapshot.SWOfflineEnabled bool`、`ConfigSnapshot.SWOfflineHTML string`；常量 `SWDirPlaceholder`。
|
||||
|
||||
- [ ] **Step 1: 追加占位符常量**
|
||||
|
||||
在 `types.go` 占位符 const 块（第 23 行 `ErrorPageTmplPlaceholder` 后）追加：
|
||||
|
||||
```go
|
||||
SWDirPlaceholder = "__OPENFLARE_SW_DIR__"
|
||||
```
|
||||
|
||||
- [ ] **Step 2: 追加 ConfigSnapshot 字段**
|
||||
|
||||
在 `ConfigSnapshot` 末尾（`OriginErrorPageGetOnly` 后）追加：
|
||||
|
||||
```go
|
||||
// SWOfflineEnabled enables the Service Worker offline fallback for HTTPS routes.
|
||||
SWOfflineEnabled bool `json:"sw_offline_enabled,omitempty"`
|
||||
// SWOfflineHTML is the contact-page HTML served offline; empty uses the built-in default.
|
||||
SWOfflineHTML string `json:"sw_offline_html,omitempty"`
|
||||
```
|
||||
|
||||
- [ ] **Step 3: 提交**
|
||||
|
||||
```bash
|
||||
git add pkg/render/openresty/types.go
|
||||
git commit -m "feat(openresty): add sw offline ConfigSnapshot fields and placeholder"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Task 4: 渲染层 SW 资源与挑战拦截
|
||||
|
||||
**Files:**
|
||||
- Create: `pkg/render/openresty/service_worker.go`
|
||||
- Create: `pkg/render/openresty/service_worker_test.go`
|
||||
- Modify: `pkg/render/openresty/render.go:37-59`（`Render` 追加 support files）
|
||||
- Modify: `pkg/render/openresty/render.go:90-115`（`RenderRouteConfig` 注入挑战）
|
||||
|
||||
**Interfaces:**
|
||||
- Consumes: `ConfigSnapshot.SWOfflineEnabled` / `.SWOfflineHTML`；`SWDirPlaceholder`。
|
||||
- Produces: `DefaultSWOfflineHTML string`、`EffectiveSWOfflineHTML(cfg ConfigSnapshot) string`、`ServiceWorkerSupportFiles(cfg ConfigSnapshot) []SupportFile`、`renderServiceWorkerChallenger(cfg ConfigSnapshot) string`。
|
||||
|
||||
- [ ] **Step 1: 写失败测试**
|
||||
|
||||
创建 `service_worker_test.go`，断言：
|
||||
1. `EffectiveSWOfflineHTML`：HTML 为空返回内置默认；非空返回自定义。
|
||||
2. `ServiceWorkerSupportFiles`：仅当 `SWOfflineEnabled` 时返回 `sw/sw.js` 与 `sw/offline.html` 两个文件；未启用返回 nil。
|
||||
3. `renderServiceWorkerChallenger`：启用且含 sw.js location、offline location、挑战 location；未启用返回空串。
|
||||
|
||||
```go
|
||||
package openresty
|
||||
|
||||
import (
|
||||
"strings"
|
||||
"testing"
|
||||
)
|
||||
|
||||
func TestEffectiveSWOfflineHTML(t *testing.T) {
|
||||
if got := EffectiveSWOfflineHTML(ConfigSnapshot{}); got != DefaultSWOfflineHTML {
|
||||
t.Fatalf("default mismatch")
|
||||
}
|
||||
custom := "<html>custom</html>"
|
||||
if got := EffectiveSWOfflineHTML(ConfigSnapshot{SWOfflineHTML: custom}); got != custom {
|
||||
t.Fatalf("custom mismatch")
|
||||
}
|
||||
}
|
||||
|
||||
func TestServiceWorkerSupportFiles(t *testing.T) {
|
||||
disabled := ServiceWorkerSupportFiles(ConfigSnapshot{})
|
||||
if disabled != nil {
|
||||
t.Fatalf("expected nil when disabled, got %v", disabled)
|
||||
}
|
||||
enabled := ServiceWorkerSupportFiles(ConfigSnapshot{SWOfflineEnabled: true})
|
||||
if len(enabled) != 2 {
|
||||
t.Fatalf("expected 2 support files, got %d", len(enabled))
|
||||
}
|
||||
paths := map[string]string{}
|
||||
for _, f := range enabled {
|
||||
paths[f.Path] = f.Content
|
||||
}
|
||||
if _, ok := paths["sw/sw.js"]; !ok {
|
||||
t.Fatalf("missing sw/sw.js")
|
||||
}
|
||||
if _, ok := paths["sw/offline.html"]; !ok {
|
||||
t.Fatalf("missing sw/offline.html")
|
||||
}
|
||||
}
|
||||
|
||||
func TestRenderServiceWorkerChallenger(t *testing.T) {
|
||||
if got := renderServiceWorkerChallenger(ConfigSnapshot{}); got != "" {
|
||||
t.Fatalf("expected empty when disabled")
|
||||
}
|
||||
got := renderServiceWorkerChallenger(ConfigSnapshot{SWOfflineEnabled: true})
|
||||
for _, want := range []string{"location = /sw.js", "location = /offline.html", "sw.runtime", "content_by_lua"} {
|
||||
if !strings.Contains(got, want) {
|
||||
t.Fatalf("challenger missing %q", want)
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
- [ ] **Step 2: 运行确认失败**
|
||||
|
||||
Run: `go test ./pkg/render/openresty/ -run 'TestEffectiveSWOfflineHTML|TestServiceWorkerSupportFiles|TestRenderServiceWorkerChallenger'`
|
||||
Expected: FAIL（函数未定义）
|
||||
|
||||
- [ ] **Step 3: 实现 `service_worker.go`**
|
||||
|
||||
```go
|
||||
package openresty
|
||||
|
||||
import (
|
||||
"strings"
|
||||
)
|
||||
|
||||
const (
|
||||
SWJSLocation = "location = /sw.js"
|
||||
SWOfflineLocation = "location = /offline.html"
|
||||
SWChallengeLua = "sw/challenge.lua"
|
||||
SWRuntimeLua = "sw/runtime.lua"
|
||||
swDirPrefix = "sw/"
|
||||
)
|
||||
|
||||
// DefaultSWOfflineHTML is the built-in contact page shown when the domain is blocked.
|
||||
const DefaultSWOfflineHTML = `<!DOCTYPE html>
|
||||
<html lang="zh-CN">
|
||||
<head>
|
||||
<meta charset="UTF-8">
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||||
<title>网站暂时无法访问 | 联系站长</title>
|
||||
<style>
|
||||
* { box-sizing: border-box; margin: 0; padding: 0; }
|
||||
body { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif; background: #ffffff; color: #333333; height: 100vh; display: flex; flex-direction: column; justify-content: center; align-items: center; text-align: center; padding: 48px 24px; }
|
||||
h1 { font-size: 28px; font-weight: 700; margin-bottom: 16px; }
|
||||
p { font-size: 16px; line-height: 1.7; color: #666666; max-width: 520px; }
|
||||
</style>
|
||||
</head>
|
||||
<body>
|
||||
<h1>网站暂时无法访问</h1>
|
||||
<p>当前域名暂时无法从网络访问。请通过其他方式联系网站管理员获取最新访问入口。</p>
|
||||
</body>
|
||||
</html>
|
||||
`
|
||||
|
||||
// EffectiveSWOfflineHTML returns custom HTML when set, otherwise the built-in default.
|
||||
func EffectiveSWOfflineHTML(cfg ConfigSnapshot) string {
|
||||
if strings.TrimSpace(cfg.SWOfflineHTML) == "" {
|
||||
return DefaultSWOfflineHTML
|
||||
}
|
||||
return cfg.SWOfflineHTML
|
||||
}
|
||||
|
||||
// ServiceWorkerSupportFiles returns the sw.js script and offline contact page.
|
||||
func ServiceWorkerSupportFiles(cfg ConfigSnapshot) []SupportFile {
|
||||
if !cfg.SWOfflineEnabled {
|
||||
return nil
|
||||
}
|
||||
return []SupportFile{
|
||||
{Path: swDirPrefix + "sw.js", Content: defaultSWJS()},
|
||||
{Path: swDirPrefix + "offline.html", Content: EffectiveSWOfflineHTML(cfg)},
|
||||
}
|
||||
}
|
||||
|
||||
func defaultSWJS() string {
|
||||
return `var CACHE = "openflare-offline-v1";
|
||||
var OFFLINE = "/offline.html";
|
||||
self.addEventListener("install", function (e) {
|
||||
e.waitUntil(caches.open(CACHE).then(function (c) { return c.addAll([OFFLINE]); }));
|
||||
self.skipWaiting();
|
||||
});
|
||||
self.addEventListener("activate", function (e) {
|
||||
e.waitUntil(caches.keys().then(function (keys) {
|
||||
return Promise.all(keys.filter(function (k) { return k !== CACHE; }).map(function (k) { return caches.delete(k); }));
|
||||
}));
|
||||
self.clients.claim();
|
||||
});
|
||||
self.addEventListener("fetch", function (e) {
|
||||
if (e.request.method !== "GET") { return; }
|
||||
e.respondWith(
|
||||
fetch(e.request).catch(function () {
|
||||
return caches.match(e.request).then(function (r) { return r || caches.match(OFFLINE); });
|
||||
})
|
||||
);
|
||||
});
|
||||
`
|
||||
}
|
||||
|
||||
// renderServiceWorkerChallenger emits SW static locations and the homepage
|
||||
// challenge intercept for HTTPS server blocks.
|
||||
func renderServiceWorkerChallenger(cfg ConfigSnapshot) string {
|
||||
if !cfg.SWOfflineEnabled {
|
||||
return ""
|
||||
}
|
||||
var builder strings.Builder
|
||||
builder.WriteString("\n location = /sw.js {\n")
|
||||
builder.WriteString(" alias " + SWDirPlaceholder + "/sw.js;\n")
|
||||
builder.WriteString(" default_type application/javascript;\n")
|
||||
builder.WriteString(" add_header Service-Worker-Allowed /;\n")
|
||||
builder.WriteString(" add_header Cache-Control \"no-cache\";\n")
|
||||
builder.WriteString(" }\n\n")
|
||||
builder.WriteString(" location = /offline.html {\n")
|
||||
builder.WriteString(" alias " + SWDirPlaceholder + "/offline.html;\n")
|
||||
builder.WriteString(" default_type text/html;\n")
|
||||
builder.WriteString(" add_header Cache-Control \"no-cache\";\n")
|
||||
builder.WriteString(" }\n\n")
|
||||
builder.WriteString(" location = /__openflare_sw_challenge {\n")
|
||||
builder.WriteString(" internal;\n")
|
||||
builder.WriteString(" content_by_lua_file " + SWDirPlaceholder + "/challenge.lua;\n")
|
||||
builder.WriteString(" }\n")
|
||||
return builder.String()
|
||||
}
|
||||
```
|
||||
|
||||
- [ ] **Step 4: 接入 `Render` 追加 support files**
|
||||
|
||||
在 `render.go` `Render` 函数内、`originErrorPageSupportFile` 追加之后追加：
|
||||
|
||||
```go
|
||||
if doc.OpenRestyConfig.SWOfflineEnabled {
|
||||
files = append(files, ServiceWorkerSupportFiles(doc.OpenRestyConfig)...)
|
||||
}
|
||||
```
|
||||
|
||||
- [ ] **Step 5: 接入 `RenderRouteConfig` 注入挑战**
|
||||
|
||||
在 `RenderRouteConfig` 内 `renderProxyRoute` / `renderPagesRoute` 调用之前，将 SW 拦截接入 server 块。将 `renderAccessBlock(siteName, powEnabled)` 调用处扩展：新建 `renderServerAccess(siteName, powEnabled, cfg)` 封装，并在其中追加 SW 运行时检查。具体为在 `renderAccessBlock` 生成的 access 块内，追加对 `sw.runtime` 的调用。
|
||||
|
||||
简化实现：新增 `renderAccessBlockWithSW(siteName string, powEnabled bool, cfg ConfigSnapshot) string`，返回 `renderAccessBlock(siteName, powEnabled)` 与（当 `SWOfflineEnabled` 时）追加：
|
||||
|
||||
```
|
||||
access_by_lua_block {
|
||||
if not string.find(package.path, "__OPENFLARE_LUA_DIR__/?.lua", 1, true) then
|
||||
package.path = "__OPENFLARE_LUA_DIR__/?.lua;__OPENFLARE_LUA_DIR__/?/init.lua;" .. package.path
|
||||
end
|
||||
require("sw.runtime").check()
|
||||
}
|
||||
```
|
||||
|
||||
然后将 `renderHTTPProxyServer`、`renderHTTPSServer`、`renderHTTPPagesServer`、`renderHTTPSPagesServer` 中 `renderAccessBlock(...)` 替换为 `renderAccessBlockWithSW(..., cfg)`，并在各自 server 块内追加 `renderServiceWorkerChallenger(cfg)` 输出。
|
||||
|
||||
**注意：** `renderAccessBlock` 在既有 powEnabled 分支已含 `access_by_lua_block`。为兼容，`renderAccessBlockWithSW` 在 powEnabled 分支内合并 SW check 到同一块；非 pow 分支额外追加一个块。本步以**仅新增 server 级 SW location + 独立 `access_by_lua_block`** 为最小实现；若 nginx 同 server 存在两个 `access_by_lua_block`，运行时只执行最后一个——**故实现必须合并**。请在实现时确认 `renderAccessBlock` 各分支，将 SW check 合并进唯一 access 块内，避免覆盖 WAF/PoW。
|
||||
|
||||
- [ ] **Step 6: 运行测试**
|
||||
|
||||
Run: `go test ./pkg/render/openresty/...`
|
||||
Expected: PASS
|
||||
|
||||
- [ ] **Step 7: 提交**
|
||||
|
||||
```bash
|
||||
git add pkg/render/openresty/service_worker.go pkg/render/openresty/service_worker_test.go pkg/render/openresty/render.go
|
||||
git commit -m "feat(openresty): render sw offline assets and challenge intercept"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Task 5: config_version snapshot 接入全局 Option
|
||||
|
||||
**Files:**
|
||||
- Modify: `internal/apps/openflare/config_version/snapshot.go:143-147`（`openRestyConfigSnapshot` 字段）
|
||||
- Modify: `internal/apps/openflare/config_version/snapshot.go:559-563`（`buildOpenRestyConfigSnapshot` 读取）
|
||||
- Modify: `internal/apps/openflare/config_version/logics.go:537-541`（diff 追加）
|
||||
- Modify: `internal/apps/openflare/config_version/logics.go:604-608`（option keys 追加）
|
||||
|
||||
**Interfaces:**
|
||||
- Consumes: `model.ConfigKeySWOfflineEnabled` / `.SWOfflineHTML`。
|
||||
- Produces: snapshot JSON 内 `sw_offline_enabled` / `sw_offline_html` 字段，触发 checksum 变化。
|
||||
|
||||
- [ ] **Step 1: snapshot 结构体追加字段**
|
||||
|
||||
在 `openRestyConfigSnapshot`（`snapshot.go:143-147`，`OriginErrorPageGetOnly` 后）追加：
|
||||
|
||||
```go
|
||||
SWOfflineEnabled bool `json:"sw_offline_enabled,omitempty"`
|
||||
SWOfflineHTML string `json:"sw_offline_html,omitempty"`
|
||||
```
|
||||
|
||||
- [ ] **Step 2: build 读取配置**
|
||||
|
||||
在 `buildOpenRestyConfigSnapshot`（`snapshot.go:559-563`，`OriginErrorPageGetOnly` 赋值后）追加：
|
||||
|
||||
```go
|
||||
SWOfflineEnabled: getBoolConfig(model.ConfigKeySWOfflineEnabled, false),
|
||||
SWOfflineHTML: getStringConfig(model.ConfigKeySWOfflineHTML, ""),
|
||||
```
|
||||
|
||||
- [ ] **Step 3: diff 追加**
|
||||
|
||||
在 `diffOpenRestyOptionDetails`（`logics.go:540` 后）追加：
|
||||
|
||||
```go
|
||||
appendIfChanged("SWOfflineEnabled", fmt.Sprintf("%t", left.SWOfflineEnabled), fmt.Sprintf("%t", right.SWOfflineEnabled))
|
||||
appendIfChanged("SWOfflineHTML", left.SWOfflineHTML, right.SWOfflineHTML)
|
||||
```
|
||||
|
||||
- [ ] **Step 4: option keys 追加**
|
||||
|
||||
在 `openRestyOptionKeys()`（`logics.go:607` 后）追加：
|
||||
|
||||
```go
|
||||
"SWOfflineEnabled",
|
||||
"SWOfflineHTML",
|
||||
```
|
||||
|
||||
- [ ] **Step 5: 运行测试**
|
||||
|
||||
Run: `go test ./internal/apps/openflare/config_version/...`
|
||||
Expected: PASS
|
||||
|
||||
- [ ] **Step 6: 提交**
|
||||
|
||||
```bash
|
||||
git add internal/apps/openflare/config_version/snapshot.go internal/apps/openflare/config_version/logics.go
|
||||
git commit -m "feat(config): wire sw offline options into config snapshot"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Task 6: Agent 侧 SW Lua 资源与占位符替换
|
||||
|
||||
**Files:**
|
||||
- Create: `internal/apps/agent/nginx/sw_assets.go`
|
||||
- Modify: `internal/apps/agent/nginx/manager.go:393-410`（`EnsureLuaAssets` 追加 SW Lua）
|
||||
- Modify: `internal/apps/agent/nginx/manager.go:526-528`（checksum 归一化 SW 路径）
|
||||
- Modify: `internal/apps/agent/nginx/manager.go:1381-1383`（renderRouteConfig 替换 SW 占位符）
|
||||
|
||||
**Interfaces:**
|
||||
- Consumes: `openrestyrender.SWDirPlaceholder`、`openrestyrender.SWChallengeLua`、`openrestyrender.SWRuntimeLua`。
|
||||
- Produces: `ManagedSWLuaFiles() []protocol.SupportFile`（`sw/runtime.lua`、`sw/challenge.lua`）。
|
||||
|
||||
- [ ] **Step 1: 创建 `sw_assets.go`**
|
||||
|
||||
```go
|
||||
package nginx
|
||||
|
||||
import (
|
||||
"github.com/Rain-kl/Wavelet/internal/apps/agent/protocol"
|
||||
)
|
||||
|
||||
const openRestySWRuntimeLua = `local source = debug.getinfo(1, "S").source or ""
|
||||
if string.sub(source, 1, 1) == "@" then
|
||||
local script_path = string.sub(source, 2)
|
||||
local base_dir = string.match(script_path, "^(.*)/sw/[^/]+%.lua$")
|
||||
if base_dir and base_dir ~= "" and not string.find(package.path, base_dir, 1, true) then
|
||||
package.path = base_dir .. "/?.lua;" .. base_dir .. "/?/init.lua;" .. package.path
|
||||
end
|
||||
end
|
||||
|
||||
local function is_real_browser(ua)
|
||||
if not ua or ua == "" then return false end
|
||||
-- Chrome/Edge/CentOS-style: "Chrome/120"
|
||||
if string.find(ua, "Chrome/%d", 1, true) then return true end
|
||||
-- Firefox: "Firefox/120"
|
||||
if string.find(ua, "Firefox/%d", 1, true) then return true end
|
||||
-- Safari (non-Chrome, e.g. "Version/17.0 Safari")
|
||||
if not string.find(ua, "Chrome", 1, true) and string.find(ua, "Safari", 1, true) then return true end
|
||||
return false
|
||||
end
|
||||
|
||||
local function pass_through()
|
||||
return true
|
||||
end
|
||||
|
||||
function _M_check()
|
||||
local ua = ngx.var.http_user_agent or ""
|
||||
if not is_real_browser(ua) then return pass_through() end
|
||||
|
||||
local uri = ngx.var.uri or ""
|
||||
if uri ~= "/" then return pass_through() end
|
||||
|
||||
local cookie = ngx.var["cookie___openflare_sw"]
|
||||
if cookie and cookie ~= "" then return pass_through() end
|
||||
|
||||
-- intercept: internal redirect to challenge page, which registers SW + sets cookie
|
||||
local redir = ngx.var.scheme .. "://" .. ngx.var.host .. uri .. (ngx.var.args and ("?" .. ngx.var.args) or "")
|
||||
ngx.req.set_uri_args({ redir = redir })
|
||||
return ngx.exec("/__openflare_sw_challenge")
|
||||
end
|
||||
`
|
||||
|
||||
const openRestySWChallengeLua = `local args = ngx.req.get_uri_args()
|
||||
local redir = args["redir"] or "/"
|
||||
ngx.header["Set-Cookie"] = "__openflare_sw=1; Path=/; Max-Age=31536000"
|
||||
ngx.header.content_type = "text/html; charset=utf-8"
|
||||
ngx.say([[<!DOCTYPE html>
|
||||
<html lang="zh-CN">
|
||||
<head>
|
||||
<meta charset="utf-8">
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1">
|
||||
<meta name="robots" content="noindex,nofollow">
|
||||
<title>加载中...</title>
|
||||
<script>
|
||||
if ("serviceWorker" in navigator) {
|
||||
navigator.serviceWorker.register("/sw.js").then(function () {
|
||||
location.replace("]] .. redir .. [[");
|
||||
}).catch(function () {
|
||||
location.replace("]] .. redir .. [[");
|
||||
});
|
||||
} else {
|
||||
location.replace("]] .. redir .. [[");
|
||||
}
|
||||
</script>
|
||||
</head>
|
||||
<body>正在加载...</body>
|
||||
</html>]])
|
||||
`
|
||||
|
||||
// ManagedSWLuaFiles returns embedded Lua assets for the SW offline challenge.
|
||||
func ManagedSWLuaFiles() []protocol.SupportFile {
|
||||
return []protocol.SupportFile{
|
||||
{Path: "sw/runtime.lua", Content: openRestySWRuntimeLua},
|
||||
{Path: "sw/challenge.lua", Content: openRestySWChallengeLua},
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
- [ ] **Step 2: `EnsureLuaAssets` 追加 SW Lua**
|
||||
|
||||
在 `manager.go:403`（`allSupportFiles` 组装处）追加：
|
||||
|
||||
```go
|
||||
allSupportFiles = append(allSupportFiles, ManagedSWLuaFiles()...)
|
||||
```
|
||||
|
||||
- [ ] **Step 3: checksum 归一化 SW 路径**
|
||||
|
||||
在 `manager.go:526-528`（error page 路径归一化后）追加：
|
||||
|
||||
```go
|
||||
swDir := filepath.ToSlash(filepath.Join(m.NginxCertDir, "sw"))
|
||||
normalizedRoute = strings.ReplaceAll(normalizedRoute, swDir, openrestyrender.SWDirPlaceholder)
|
||||
```
|
||||
|
||||
- [ ] **Step 4: `renderRouteConfig` 替换 SW 占位符**
|
||||
|
||||
在 `manager.go:1381-1383`（error page 替换后）追加：
|
||||
|
||||
```go
|
||||
swDir := filepath.ToSlash(filepath.Join(m.NginxCertDir, "sw"))
|
||||
rendered = strings.ReplaceAll(rendered, openrestyrender.SWDirPlaceholder, swDir)
|
||||
```
|
||||
|
||||
- [ ] **Step 5: 确认 SW 文件落盘**
|
||||
|
||||
`renderServiceWorkerChallenger` 中 `alias __OPENFLARE_SW_DIR__/sw.js` 与 `/offline.html` 引用 support files `sw/sw.js`、`sw/offline.html`。这些文件经 Task 4 作为普通 support file 由 `writeManagedCertFiles` 写入 `<CertDir>/sw/`（路径含子目录）。验证 `certFileTargetPath` 支持子目录路径（读 `manager.go` 确认）。若不支持，需在 `writeManagedCertFiles` 中 `os.MkdirAll(filepath.Dir(targetPath))`。**实现时确认并补全目录创建。**
|
||||
|
||||
- [ ] **Step 6: 运行测试**
|
||||
|
||||
Run: `go build ./... && go test ./internal/apps/agent/nginx/...`
|
||||
Expected: PASS
|
||||
|
||||
- [ ] **Step 7: 提交**
|
||||
|
||||
```bash
|
||||
git add internal/apps/agent/nginx/sw_assets.go internal/apps/agent/nginx/manager.go
|
||||
git commit -m "feat(agent): ship sw offline lua assets and placeholder substitution"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Task 7: 前端「响应页面」模块（两个 tab）
|
||||
|
||||
**Files:**
|
||||
- Create: `frontend/app/(main)/responses/page.tsx`
|
||||
- Create: `frontend/app/(main)/responses/components/contact-page-tab.tsx`
|
||||
- Create: `frontend/app/(main)/responses/components/shared.ts`
|
||||
- Modify: `frontend/lib/navigation/openflare-nav.ts:63-67`
|
||||
- Modify: `frontend/lib/navigation/openflare-nav.ts:123`
|
||||
|
||||
**Interfaces:**
|
||||
- Consumes: `OptionService.list()` / `OptionService.updateBatch()`（已存在）。
|
||||
- Produces: 联系页 tab 编辑 `sw_offline_enabled` / `sw_offline_html` 两个 option。
|
||||
|
||||
- [ ] **Step 1: 创建共享 helper `shared.ts`**
|
||||
|
||||
```ts
|
||||
export const OPTIONS_QUERY_KEY = ['openflare', 'options'] as const;
|
||||
|
||||
export const KEY_SW_ENABLED = 'sw_offline_enabled';
|
||||
export const KEY_SW_HTML = 'sw_offline_html';
|
||||
|
||||
export type ContactPageFields = {
|
||||
enabled: boolean;
|
||||
html: string;
|
||||
};
|
||||
|
||||
export const defaultContactPageFields: ContactPageFields = {
|
||||
enabled: false,
|
||||
html: '',
|
||||
};
|
||||
|
||||
export function optionsToMap(options: Array<{ key: string; value: string }>) {
|
||||
return options.reduce<Record<string, string>>((acc, option) => {
|
||||
acc[option.key] = option.value;
|
||||
return acc;
|
||||
}, {});
|
||||
}
|
||||
|
||||
export function mapOptionsToContactFields(
|
||||
optionMap: Record<string, string>,
|
||||
): ContactPageFields {
|
||||
return {
|
||||
enabled: optionMap[KEY_SW_ENABLED] === 'true',
|
||||
html: optionMap[KEY_SW_HTML] ?? '',
|
||||
};
|
||||
}
|
||||
|
||||
export async function invalidateResponseQueries(queryClient: {
|
||||
invalidateQueries: (opts: {
|
||||
queryKey: readonly unknown[];
|
||||
}) => Promise<unknown>;
|
||||
}) {
|
||||
await Promise.all([
|
||||
queryClient.invalidateQueries({ queryKey: OPTIONS_QUERY_KEY }),
|
||||
queryClient.invalidateQueries({
|
||||
queryKey: ['openflare', 'config-preview'],
|
||||
}),
|
||||
queryClient.invalidateQueries({
|
||||
queryKey: ['openflare', 'config-versions'],
|
||||
}),
|
||||
]);
|
||||
}
|
||||
```
|
||||
|
||||
- [ ] **Step 2: 创建联系页 tab `contact-page-tab.tsx`**
|
||||
|
||||
参考 `error-pages/page.tsx` 交互：一个「启用」开关 + 一个 HTML 文本域 + 保存按钮。保存 `updateBatch([{key: KEY_SW_ENABLED,...},{key: KEY_SW_HTML,...}])`，成功后 `invalidateResponseQueries`。
|
||||
|
||||
```tsx
|
||||
'use client';
|
||||
|
||||
import { useEffect, useState } from 'react';
|
||||
import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query';
|
||||
import { Loader2, Save } from 'lucide-react';
|
||||
import { toast } from 'sonner';
|
||||
|
||||
import { Button } from '@/components/ui/button';
|
||||
import {
|
||||
Card,
|
||||
CardContent,
|
||||
CardDescription,
|
||||
CardHeader,
|
||||
CardTitle,
|
||||
} from '@/components/ui/card';
|
||||
import { Label } from '@/components/ui/label';
|
||||
import { Switch } from '@/components/ui/switch';
|
||||
import { Textarea } from '@/components/ui/textarea';
|
||||
import { OptionService } from '@/lib/services/openflare';
|
||||
|
||||
import {
|
||||
defaultContactPageFields,
|
||||
invalidateResponseQueries,
|
||||
KEY_SW_ENABLED,
|
||||
KEY_SW_HTML,
|
||||
mapOptionsToContactFields,
|
||||
optionsToMap,
|
||||
type ContactPageFields,
|
||||
} from './shared';
|
||||
|
||||
export function ContactPageTab({ optionMap }: { optionMap: Record<string, string> }) {
|
||||
const queryClient = useQueryClient();
|
||||
const [fields, setFields] = useState<ContactPageFields>(
|
||||
defaultContactPageFields,
|
||||
);
|
||||
|
||||
useEffect(() => {
|
||||
setFields(mapOptionsToContactFields(optionMap));
|
||||
}, [optionMap]);
|
||||
|
||||
const saveMutation = useMutation({
|
||||
mutationFn: async () => {
|
||||
await OptionService.updateBatch([
|
||||
{ key: KEY_SW_ENABLED, value: String(fields.enabled) },
|
||||
{ key: KEY_SW_HTML, value: fields.html },
|
||||
]);
|
||||
},
|
||||
onSuccess: async () => {
|
||||
toast.success('联系页已保存，请前往版本发布使配置生效');
|
||||
await invalidateResponseQueries(queryClient);
|
||||
},
|
||||
onError: (error) => {
|
||||
toast.error(error instanceof Error ? error.message : '保存失败');
|
||||
},
|
||||
});
|
||||
|
||||
return (
|
||||
<div className='space-y-6'>
|
||||
<Card className='border-dashed shadow-none'>
|
||||
<CardHeader className='flex flex-row items-start justify-between gap-4 space-y-0'>
|
||||
<div className='space-y-1.5'>
|
||||
<CardTitle className='text-base'>离线兜底</CardTitle>
|
||||
<CardDescription>
|
||||
启用后给启用 HTTPS 的网站下发 Service Worker，域名被墙时浏览器从缓存展示此联系页。
|
||||
</CardDescription>
|
||||
</div>
|
||||
<Button
|
||||
size='sm'
|
||||
className='shrink-0'
|
||||
disabled={saveMutation.isPending}
|
||||
onClick={() => saveMutation.mutate()}
|
||||
>
|
||||
{saveMutation.isPending ? (
|
||||
<Loader2 className='size-3.5 animate-spin' />
|
||||
) : (
|
||||
<Save className='size-3.5' />
|
||||
)}
|
||||
保存
|
||||
</Button>
|
||||
</CardHeader>
|
||||
<CardContent className='space-y-4'>
|
||||
<div className='flex items-start justify-between gap-6'>
|
||||
<div className='space-y-1'>
|
||||
<Label className='text-sm font-medium'>启用 Service Worker 离线兜底</Label>
|
||||
<p className='text-sm text-muted-foreground'>
|
||||
仅对 HTTPS 网站生效；未启用的站点不受影响。
|
||||
</p>
|
||||
</div>
|
||||
<Switch
|
||||
checked={fields.enabled}
|
||||
onCheckedChange={(enabled) =>
|
||||
setFields((prev) => ({ ...prev, enabled }))
|
||||
}
|
||||
aria-label='启用离线兜底'
|
||||
className='mt-0.5 shrink-0'
|
||||
/>
|
||||
</div>
|
||||
<div className='flex flex-col gap-3'>
|
||||
<Label htmlFor='sw-offline-html' className='text-sm font-medium'>
|
||||
离线联系页 HTML
|
||||
</Label>
|
||||
<p className='text-sm text-muted-foreground'>
|
||||
留空则使用内置默认模板。
|
||||
</p>
|
||||
<Textarea
|
||||
id='sw-offline-html'
|
||||
value={fields.html}
|
||||
onChange={(e) =>
|
||||
setFields((prev) => ({ ...prev, html: e.target.value }))
|
||||
}
|
||||
rows={12}
|
||||
className='font-mono'
|
||||
disabled={!fields.enabled}
|
||||
/>
|
||||
</div>
|
||||
</CardContent>
|
||||
</Card>
|
||||
</div>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
**注意：** 确认 `frontend/components/ui/` 存在 `textarea.tsx`（shadcn）。若无，用 `make sure` 或 `npx shadcn@latest add textarea` 添加。
|
||||
|
||||
- [ ] **Step 3: 创建页面容器 `responses/page.tsx`**
|
||||
|
||||
用 Tabs 组件组织「错误页」「联系页」两个 tab。错误页 tab 复用现有 `error-pages` 内容或重定向；联系页 tab 渲染 `ContactPageTab`。加载 `OptionService.list()` 传入 optionMap。
|
||||
|
||||
**实现提示：** 为避免重复，错误页 tab 的现有逻辑（`error-pages/page.tsx` 的 policy 卡片 + 预览卡）可先以 `redirect` 到 `/error-pages` 占位，或直接在容器内嵌两 tab。推荐：容器页 `responses/page.tsx` 读取 options，渲染 Tabs（错误页/联系页），错误页 tab 复用 `frontend/app/(main)/error-pages` 现有 UI（通过 import 其组件或在容器内重构）。**保守实现：** 容器页仅放两个 tab，错误页 tab 用 `<Link href='/error-pages'>` 或保留现有 `/error-pages` 路由，联系页 tab 显示新表单；导航入口改为「响应页面」指向 `/responses`。
|
||||
|
||||
- [ ] **Step 4: 更新导航**
|
||||
|
||||
`openflare-nav.ts` 第 63-67 行将「错误页」项改为「响应页面」：
|
||||
|
||||
```ts
|
||||
{
|
||||
title: '响应页面',
|
||||
url: '/responses',
|
||||
childUrls: ['/error-pages', '/responses/contact'],
|
||||
},
|
||||
```
|
||||
|
||||
第 123 行 `openflareWebsiteSubNav` 中 `{ title: '错误页', url: '/error-pages' }` 改为 `{ title: '响应页面', url: '/responses' }`。
|
||||
|
||||
- [ ] **Step 5: 构建前端**
|
||||
|
||||
Run: `cd /Users/ryan/conductor/workspaces/OpenFlare/islamabad/frontend && pnpm type-check`
|
||||
Expected: PASS
|
||||
|
||||
- [ ] **Step 6: 提交**
|
||||
|
||||
```bash
|
||||
git add frontend/app/\(main\)/responses frontend/lib/navigation/openflare-nav.ts
|
||||
git commit -m "feat(frontend): add response pages module with contact page tab"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Task 8: Changelog 与收尾验证
|
||||
|
||||
**Files:**
|
||||
- Modify: `docs/changelog/index.md`
|
||||
|
||||
**Interfaces:**
|
||||
- Produces: `[Unreleased]` 下用户可读中文条目。
|
||||
|
||||
- [ ] **Step 1: 追加 changelog**
|
||||
|
||||
在 `docs/changelog/index.md` 的 `[Unreleased]` 下追加：
|
||||
|
||||
```markdown
|
||||
### 新增
|
||||
|
||||
- 支持 Service Worker 离线兜底：为启用 HTTPS 的网站下发 Service Worker 并缓存离线联系页，域名无法访问时浏览器展示联系站长页面，减少用户流失。配置位于「响应页面」-「联系页」，可在版本发布中批量生效。
|
||||
```
|
||||
|
||||
- [ ] **Step 2: 运行完整校验**
|
||||
|
||||
Run: `cd /Users/ryan/conductor/workspaces/OpenFlare/islamabad && make code-check`
|
||||
Expected: PASS（golangci-lint + 前端类型检查）
|
||||
|
||||
- [ ] **Step 3: 运行后端全量测试**
|
||||
|
||||
Run: `go test ./...`
|
||||
Expected: PASS
|
||||
|
||||
- [ ] **Step 4: 格式化**
|
||||
|
||||
Run: `cd /Users/ryan/conductor/workspaces/OpenFlare/islamabad && make format`
|
||||
Expected: 无格式变更或已应用
|
||||
|
||||
- [ ] **Step 5: 提交**
|
||||
|
||||
```bash
|
||||
git add docs/changelog/index.md
|
||||
git commit -m "docs: sw offline fallback changelog"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Self-Review
|
||||
|
||||
**Spec 覆盖检查：**
|
||||
- 全局 Option（sw_offline_enabled / html）→ Task 1-3、5 ✓
|
||||
- 渲染层 SW 静态 + 挑战拦截（反代 + Pages，HTTPS-only）→ Task 4 ✓
|
||||
- SupportFile 下发 sw.js / offline.html，Agent 占位符替换 → Task 4、6 ✓
|
||||
- UA 白名单（真实浏览器特征）→ Task 6 `is_real_browser` ✓
|
||||
- Cookie 长过期 + 首次挑战页 → Task 6 ✓
|
||||
- 前端「响应页面」两 tab → Task 7 ✓
|
||||
- 迁移 seed → Task 2 ✓
|
||||
- Changelog → Task 8 ✓
|
||||
|
||||
**占位符扫描：** 无 TBD/TODO。Task 4 Step 5 与 Task 7 Step 3 保留实现细节提示（非占位，是给定方向让执行者按实际代码确认），已在文中明确标注"实现时确认"。
|
||||
|
||||
**类型一致性：** `ConfigSnapshot.SWOfflineEnabled/HTML` 在 Task 3/4/5 一致；`SWDirPlaceholder` 在 Task 3/4/6 一致；`sw_offline_enabled/sw_offline_html` key 在 Task 1/2/5/7 一致；`renderServiceWorkerChallenger`/`ServiceWorkerSupportFiles`/`EffectiveSWOfflineHTML`/`ManagedSWLuaFiles` 签名跨 Task 一致。
|
||||
|
||||
**已知待确认项（执行时需按实际代码落地）：**
|
||||
- Task 4：`renderAccessBlock` 的 access 块合并（避免 WAF/PoW 被覆盖）。
|
||||
- Task 6：`certFileTargetPath` 是否支持子目录，落盘目录创建。
|
||||
- Task 7：`textarea` 组件存在性；「响应页面」错误页 tab 与现有 `/error-pages` 路由的复用策略。
|
||||
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,177 @@
|
||||
# 日志数据库解耦设计（ClickHouse 可选化）
|
||||
|
||||
> 状态：已与用户逐段确认，待用户复核。
|
||||
> 日期：2026-08-08
|
||||
|
||||
## 1. 背景与目标
|
||||
|
||||
当前系统日志/分析（访问日志、可观测时序）完全绑定 ClickHouse：`internal/repository/analytics` 直接操作 `db.ChConn`/`db.ChDB`，apps 层（`chwriter`、`risk_control`、`admin/logs`、`admin/status`）依赖 `config.ClickHouse.Enabled` 判断可用性。业务流量小、主机性能低时 ClickHouse 负担大。
|
||||
|
||||
目标：
|
||||
|
||||
1. **解耦**：ClickHouse 变为可选项；不启用时，主库（PostgreSQL；禁用时 SQLite）完整承接全部日志功能（写入、查询、聚合、清理）。
|
||||
2. **代码级约束**：上层应用写日志不能直接调用底层库（`analyticsrepo` / `db.ChConn`），用接口 + import-lint 测试保证，而非 AGENTS.md 口头约束。
|
||||
3. **可迁移**：提供用户触发的「切换日志数据库」任务，支持 PostgreSQL/SQLite ↔ ClickHouse 数据迁移。
|
||||
4. **表结构**：CH 日志表迁入 PG/SQLite；CH 保持只有日志表的 SQL 脚本；PG/SQLite 包含全部表。
|
||||
|
||||
## 2. 现状要点
|
||||
|
||||
- 连接：`internal/infra/persistence/clickhouse.go`（`ChConn` 原生批量写 + `ChDB` GORM 查询），`init()` 依据 `clickhouse.enabled`。
|
||||
- 分析域：`internal/repository/analytics/` 直接读写 CH；apps 通过 `batchwriter` 异步 flush（`chwriter`、`risk_control`）。
|
||||
- 已有抽象雏形：`internal/repository/openflare_access_log_store.go` / `openflare_observability_store.go` 中的未导出 `accessLogStore` / `observabilityStore` 接口，默认 `clickhouseAccessLogStore{}`，测试可换 memory 实现——默认写死 CH、不可配置切换、接口未导出。
|
||||
- 迁移：主库 goose（`goose/postgres` + `goose/sqlite` 双方言）与 CH 单方言（`goose/clickhouse`）分离。
|
||||
- 历史：PG/SQLite 曾有过 `of_node_metric_snapshots`、`of_node_access_logs` 等观测表（`202606190010_create_of_observability_tables.sql`），后由 `202606200005_drop_of_node_observability_timeseries.sql` 删除（迁去 CH）。**旧 DDL 可复活改造**。
|
||||
- 任务：Asynq + `task.RegisterHandler`/`RegisterTaskMeta`；`system_cleanup`（系统垃圾清理）每日任务已存在；`of_database_auto_cleanup`（可观测清理，schedule id=102）存在。
|
||||
- 系统配置：`system_configs` 表（key/type/visibility），现有 `database_auto_cleanup_enabled` / `database_auto_cleanup_retention_days`（business）。
|
||||
|
||||
## 3. 已确认的核心决策
|
||||
|
||||
| # | 决策 |
|
||||
|---|---|
|
||||
| 1 | 范围：CH 不启用时，PG（或 SQLite）承担**全部**日志功能；聚合在 PG/SQLite 查询时实时计算，不物理建 MV 同构表。 |
|
||||
| 2 | 实现：接口定义在 repository 层；PG 用 GORM 全新实现；CH 保留现有原生批量优化（`PrepareBatch`）包进同一接口。 |
|
||||
| 3 | SQLite 是一等公民：`log_database` ∈ {`postgres`, `sqlite`, `clickhouse`}；迁移方向 PG→CH、SQLite→CH、CH→PG、CH→SQLite。 |
|
||||
| 4 | 日志库只有两种合法状态：**随主库**（`database.enabled` → postgres，否则 sqlite）或 **clickhouse**；不存在主库 PG + 日志 SQLite 的组合。 |
|
||||
| 5 | 迁移任务「切换日志数据库」：纯复制、**源数据不删除**、可重试；迁移期间**冻结日志写入**（拒绝，不排队积压）；全部成功才翻转主库标记。 |
|
||||
| 6 | 清理统一到 `system_cleanup`（每日一次，日志过期无需实时）；保留时间按**存储库**配置（`type=business`）。 |
|
||||
|
||||
## 4. 包结构与接口（方案一）
|
||||
|
||||
新增 `internal/repository/logstore/`，职责唯一：日志存储抽象。
|
||||
|
||||
```
|
||||
internal/repository/logstore/
|
||||
├── logstore.go # 导出接口：AccessLogStore / ObservabilityStore / UserAccessLogStore / CleanupStore / StatusStore
|
||||
├── provider.go # Open(ctx) 按当前日志主库返回实现；ActiveDatabase() 供状态/UI；测试可注入
|
||||
├── postgres_store.go # GORM 实现（PG 与 SQLite 共用一套，方言差异只在 goose DDL + dialect_* 小文件）
|
||||
├── dialect_postgres.go # PG 方言 SQL 片段（date_trunc / FILTER / 分区清理）
|
||||
├── dialect_sqlite.go # SQLite 方言 SQL 片段（strftime / unixepoch）
|
||||
└── clickhouse_store.go # 把现有 analyticsrepo 原生批量 + GORM 查询包进接口（零性能损耗）
|
||||
```
|
||||
|
||||
- **接口划分**（避免 40+ 方法巨型接口，合成 `logstore.Store` 结构体持有）：
|
||||
- `AccessLogStore`：节点访问日志的 InsertBatch / List / Count / RegionCounts / BucketAggregates / CountBuckets / BucketDimensions / IPAggregates / IPSummaries / CountIPSummaries / WAFIPAggregates / IPTrend / TrafficSummary / ValueCounts / NodeAggregates / DeleteAll / DeleteBefore / DeleteByNodeBefore。
|
||||
- `ObservabilityStore`：4 表（metric snapshots / edge health / frps / frpc）的 Insert / List / Delete。
|
||||
- `UserAccessLogStore`：`w_user_access_logs` 的 BatchInsert / Count / List / 统计（DailyTrend / BrowserDistribution / TopActiveUsers 等）。
|
||||
- `CleanupStore`：按保留天数清理过期数据（PG=分区 DROP + 分批 DELETE；SQLite=分批 DELETE；CH=MODIFY TTL + materialize）。
|
||||
- `StatusStore`：当前库状态、CH 运行指标（激活时）、GORM 写入器状态。
|
||||
- **消费面**：`internal/repository` 现有公开函数（`ListOpenFlareAccessLogs`、`InsertOpenFlareAccessLogsBatch`、`InsertOpenFlareMetricSnapshot` 等）**保留签名、改为一行委托 `logstore`**，apps 调用面几乎不动；apps 里现有 `analyticsrepo` 直连（`risk_control`、`chwriter`、`tasks/database_cleanup.go`、`observability/access_log_logics.go`、`admin/logs`、`admin/status`）全部改走 repository/logstore。
|
||||
- **import-lint 测试**：新增 `go test`，扫描 `internal/apps/**` 的 import，发现 `internal/repository/analytics` 或 `internal/infra/persistence`（`batchwriter` 白名单除外）即失败。这是「代码层面规避」的验收。
|
||||
- `analyticsrepo` 保留，仅被 `logstore/clickhouse_store.go` 引用（CH 实现细节）。
|
||||
|
||||
### 主库标记与启动校验
|
||||
|
||||
- `system_configs` 新增内部 key：
|
||||
- `log_database`（`postgres`/`sqlite`/`clickhouse`）：当前日志主库，仅迁移任务写入。
|
||||
- `log_db_migration`（`"migrating"`/空）：迁移冻结标记，仅迁移任务写入。
|
||||
- **首次 seed**（bootstrap Go 侧，因依赖运行时主库选择）：key 缺失时，`clickhouse.enabled` → `clickhouse`（保持现状、不丢现有 CH 数据）；否则 → 当前主库（`database.enabled` → `postgres`，否则 `sqlite`）。
|
||||
- **启动校验**（bootstrap）：
|
||||
- `log_database=clickhouse` 但 `clickhouse.enabled=false` → 启动报错：「当前日志主库为 ClickHouse 但 ClickHouse 未启用。请先重新启用 ClickHouse 配置并启动，在任务管理运行『切换日志数据库』迁移到 PostgreSQL/SQLite 后再禁用 ClickHouse」。
|
||||
- `log_database=postgres` 但 `database.enabled=false`，或 `log_database=sqlite` 但 `database.enabled=true` → 启动报错（违反「随主库或随 CH」规则）。
|
||||
- **key 保护**：`log_database`、`log_db_migration` 在配置更新接口（admin system-configs / option 校验）拒绝修改；仅迁移任务可写；启动校验兜底被篡改组合。
|
||||
- **热切换**：`logstore` 通过系统配置缓存（Redis，更新即失效）读取 `log_database`；翻转后 API 进程自动切到新实现，无需自定义跨进程协议。
|
||||
|
||||
## 5. PG/SQLite 表结构与优化
|
||||
|
||||
**新建原始日志表（PG + SQLite 双方言 goose，同版本号）**——只建原始表，**不建** CH 物化视图/聚合表（`of_access_log_hourly`、`of_node_metric_capacity_hourly` 等），PG/SQLite 查询时实时聚合：
|
||||
|
||||
| 表 | 说明 |
|
||||
|---|---|
|
||||
| `w_user_access_logs` | 用户访问日志 |
|
||||
| `of_node_access_logs` | 节点访问日志（含 user_agent/cache_status/bytes_sent/request_length/request_time_ms 现行列） |
|
||||
| `of_node_metric_snapshots` | 资源指标 |
|
||||
| `of_node_edge_health` | 边缘健康 |
|
||||
| `of_node_obs_frps` | FRPS 观测 |
|
||||
| `of_node_obs_frpc` | FRPC 观测 |
|
||||
|
||||
- **ID**：沿用 snowflake uint64（DDL 用 BIGINT，与 CH UInt64 对齐）；不换自增，保证迁移 ID 原样保留、无冲突。
|
||||
- **时间**：PG `TIMESTAMPTZ`；SQLite `DATETIME`。
|
||||
- **复合主键**：分区表主键 `(id, 时间列)`（满足 PG 分区键进唯一索引要求）。
|
||||
|
||||
### PG 优化
|
||||
|
||||
1. **分区**：仅 `of_node_access_logs`、`w_user_access_logs` 两个高频表用 PG 原生 `PARTITION BY RANGE` **按月分区**；可观测 4 表数据量小，普通表 + 索引。SQLite 无原生分区 → 普通表 + 组合索引（方言差异只留在 goose DDL，运行时 GORM 代码共用）。
|
||||
2. **批量写入**：PG/SQLite 统一 GORM `CreateInBatches`（批次 500–1000）；CH 维持原生 `PrepareBatch`。
|
||||
3. **索引**：
|
||||
- `of_node_access_logs`：`(logged_at DESC)`、`(node_id, logged_at DESC)`、`(host, logged_at DESC)`；
|
||||
- `w_user_access_logs`：`(created_at DESC)`、`(user_id, created_at DESC)`；
|
||||
- 可观测表：`(node_id, captured_at DESC)`。
|
||||
4. **聚合查询重写**：PG 用 `date_trunc` / `count(DISTINCT)` / `FILTER (WHERE ...)` 等价替换 CH 的 `toStartOfHour` / `uniqExact` / `countIf`；SQLite 用 `strftime` / `unixepoch`。时间分桶等少量方言 SQL 拆到 `dialect_postgres.go` / `dialect_sqlite.go`，store 主体方言中立。
|
||||
|
||||
### goose 迁移
|
||||
|
||||
- PG/SQLite 各新增一组建表迁移（复活并改造 `202606190010` 旧 DDL，按 database-migration 技能双方言、同版本号规则）。
|
||||
- CH 目录不动（本来就只有日志表脚本，满足「CH 保持只有日志表 SQL」）。
|
||||
|
||||
## 6. 清理（并入 system_cleanup）
|
||||
|
||||
- 日志过期清理并入 `system_cleanup`（系统垃圾清理）每日任务；`of_database_auto_cleanup` 专用 schedule（id=102）与任务下线。
|
||||
- 新增 `type=business` 配置（替换旧 `database_auto_cleanup_enabled` / `database_auto_cleanup_retention_days`）：
|
||||
- `log_retention_days_postgres`（默认 90）
|
||||
- `log_retention_days_sqlite`（默认 90）
|
||||
- `log_retention_days_clickhouse`（默认 90）
|
||||
- `CleanupStore` 按当前生效库读取对应值执行：
|
||||
- PG：分区 DROP（整月）+ 分批 DELETE（不满月）；
|
||||
- SQLite：分批 DELETE；
|
||||
- CH：`ALTER TABLE ... MODIFY TTL toDateTime(...) + INTERVAL N DAY` + materialize（保留期由配置驱动，不再依赖 DDL 写死）。
|
||||
- 旧 key `database_auto_cleanup_*` 由 goose 迁移删除，前端同步清理。
|
||||
|
||||
## 7. 迁移任务「切换日志数据库」
|
||||
|
||||
**元数据**：Asynq `openflare:log_db_switch`，管理类型 `of_log_db_switch`，名称「切换日志数据库」，参数 `target`（`postgres`/`sqlite`/`clickhouse`），`Retryable: true`。UI 按当前日志主库只展示合法目标（当前=CH → 「主库」；当前=主库 → 「ClickHouse」）。
|
||||
|
||||
**执行流程（worker 进程）**：
|
||||
|
||||
1. **校验**：`target == 当前主库` → 拒绝；`target=clickhouse` 但 CH 未启用 / `target=postgres` 但 `database.enabled=false` / `target=sqlite` 但 `database.enabled=true` → 拒绝。
|
||||
2. **写冻结**：写 `log_db_migration = "migrating"`；先让 batchwriter 把在途批次 flush 完；此后 API 进程所有日志写入路径（`risk_control`、`chwriter` 队列、agent 上报落库）检查该 key → 返回明确错误（HTTP 503「日志数据库迁移中，暂不可写」），不排队积压。
|
||||
3. **复制**：6 张原始日志表逐表、按 id 分批（每批 ~1000）读源 → 写目标（CH→主库用 GORM `CreateInBatches`；主库→CH 用原生 `PrepareBatch`）；ID 原样保留；每表/每批 `task.AppendLog` 进度。
|
||||
- **幂等前提**：开始复制前**清空目标库日志表**（任务参数「覆盖目标库已有日志」默认开启；目标库通常为空，仅「切回去」场景有旧数据）——保证失败重试可重跑不重复。
|
||||
4. **翻转**：全部成功 → 更新 `log_database = target`、清除迁移标记 → `logstore` 缓存失效自动切到新实现 → 写入恢复（走新库）。
|
||||
5. **失败**：返回错误触发 Asynq 重试；**失败时清除迁移标记**，写入继续走源库（不丢功能）；重试时重新清空目标 + 复制。
|
||||
|
||||
**双进程一致性**：迁移标记与主库标记落在 `system_configs`（Redis 缓存，worker 更新后 API 进程自动失效重读）。
|
||||
|
||||
## 8. API 与前端
|
||||
|
||||
**后端**：
|
||||
|
||||
- `GET /api/v1/admin/status/log-database`（改造现有 `/clickhouse` 状态端点）：返回当前日志主库、迁移状态（`idle`/`migrating`）、各库保留天数、当前合法迁移目标；CH 为主时附带现有 CH 运行指标，主库为主时附带 GORM 写入器状态。
|
||||
- 任务「切换日志数据库」走现有任务管理通用派发 API（`RegisterTaskMeta` + Params），无需新派发接口；执行记录/进度复用任务框架。
|
||||
- 系统配置：新增 3 个 `log_retention_days_*`（business）图形化 + 参数表可见；新增内部 `log_database`、`log_db_migration`（system、visibility=0、受保护）；下线 `database_auto_cleanup_*`。
|
||||
|
||||
**前端**：
|
||||
|
||||
- 任务管理页：出现「切换日志数据库」，参数下拉只显示合法目标；页面展示当前日志主库与迁移状态。
|
||||
- `/admin/settings` 业务配置：新增「日志保留时间」分组（PG/SQLite/CH 三个数字输入）。
|
||||
- 状态/仪表盘：日志库状态卡片（当前库 + 迁移中提示）。
|
||||
|
||||
## 9. 测试与验证
|
||||
|
||||
- **import-lint 测试**：`internal/apps/**` 不得 import `internal/repository/analytics`、`internal/infra/persistence`（`batchwriter` 白名单除外），违规即失败。
|
||||
- **logstore 单测**：GORM 实现用 SQLite 全量跑；PG 专属（分区 DROP 等）走既有集成测试路径；CH 实现复用现有 analyticsrepo 测试。
|
||||
- **迁移任务测试**：目标/组合校验、批处理与 ID 保留、清空目标、翻转标记、失败清标记回退、冻结期写入拒绝——用 memory/sqlite 双端模拟，不依赖真实 CH。
|
||||
- **清理测试**：`system_cleanup` 日志清理步骤（PG 分区 DROP / SQLite 分批 DELETE / CH TTL 修改）与保留配置读取。
|
||||
- **迁移验证**：goose 空库 Up 全量（PG/SQLite/CH 三套）、`go test ./...`、`make swagger`（API 变更）、`make code-check`、`make format`。
|
||||
|
||||
## 10. 非目标（YAGNI）
|
||||
|
||||
- 不在 PG/SQLite 物理建聚合/物化视图表（查询实时聚合）。
|
||||
- 不做 PG ↔ SQLite 日志互迁（非法组合，启动校验拒绝）。
|
||||
- 迁移成功不自动删除源库数据（保留，后续提供手动清理入口）。
|
||||
- 不引入 PG COPY 协议（GORM `CreateInBatches` 对低流量足够）。
|
||||
- 不引入自定义跨进程迁移协议（`system_configs` + Redis 缓存即可）。
|
||||
|
||||
## 11. 里程碑建议（供实现计划分解）
|
||||
|
||||
1. **M1 抽象与改造**：`logstore` 接口 + PG/SQLite 实现 + `clickhouse_store` 包装 + import-lint 测试 + repository 委托改造 + apps 直连改造 + `log_database`/`log_db_migration` key 与启动校验。
|
||||
2. **M2 表与清理**：goose 双方言建表迁移 + 保留配置 key + `system_cleanup` 日志清理步骤 + 下线 `of_database_auto_cleanup` 与旧配置。
|
||||
3. **M3 迁移任务与展示**：迁移任务 Handler + 状态端点 + 任务管理页/业务配置前端 + 日志库状态卡片。
|
||||
4. **M4 收尾**：全量验证（goose 三套、单测、`make code-check`/`swagger`/`format`）、文档同步（中文）、changelog `[Unreleased]`。
|
||||
|
||||
## 12. 实现归档说明（Task 18，2026-08-08）
|
||||
|
||||
- 设计稿第 4 节 provider 入口写作 `Open(ctx)`，实现命名为 `Active(ctx)`（按 `log_database` 解析并缓存，配置翻转后重建），另导出 `Build(ctx, database)` / `BuildForMigration(ctx, database)` 供迁移任务构造目标库 store；`ActiveDatabase(ctx)` 供状态端点。
|
||||
- 设计稿第 4 节列出的 `CleanupStore` 接口未单独落地：清理实现为包级 `CleanupExpired(ctx)`（按当前激活库保留天数删除过期日志并预建 PG 分区），由 `system_cleanup` 每日任务调用。
|
||||
- 设计稿第 4 节列举的 `tasks/database_cleanup.go` 已随 M2 下线（`of_database_auto_cleanup` 配置与前端 UI 一并移除），日志清理职责并入 `system_cleanup`。
|
||||
- 迁移复制按 id 升序分页，`copyObservability` 以每批最后一条 id 作为下一批游标（修正计划中 `lastID += n` 的近似写法）；失败回退由 `defer setMigrationFlag("")` 保证源库恢复可写，重试前先清空目标库保证幂等。
|
||||
- 其余实现决策（`SetConfigReader` 注入、`ensureWritable` 统一冻结、解析 helper 迁至 `model/analytics` 等）见计划「自检记录」，与本文档一致。
|
||||
@@ -0,0 +1,117 @@
|
||||
# Service Worker 离线兜底设计（issue #23）
|
||||
|
||||
- 日期：2026-08-08
|
||||
- 状态：设计已确认
|
||||
- 范围：Proxy Route（反代）+ Pages 静态托管 全覆盖
|
||||
|
||||
## 1. 背景与目标
|
||||
|
||||
当 CDN 域名被墙、浏览器对所有网络请求失败时，用户会直接流失。本功能通过给网站下发 Service Worker，缓存一个"联系站长"离线页；域名被墙后，SW 从缓存吐出该页，保留用户并引导联系站长。
|
||||
|
||||
核心约束：
|
||||
|
||||
- 平台一键批量下发，避免逐个 Agent 配置。
|
||||
- 不改源页代码，全部在 OpenResty 边缘层完成。
|
||||
- 覆盖反代（Proxy Route）与 Pages 静态托管两种网站类型。
|
||||
|
||||
## 2. 机制总览
|
||||
|
||||
采用「首次挑战页 + Cookie 放行 + UA 白名单」模式，替代 `sub_filter` 响应体重写。
|
||||
|
||||
| 环节 | 行为 |
|
||||
|---|---|
|
||||
| 真实浏览器 UA（含特征版本，如 `Chrome/120`）首次访问首页 | 返回 SW 挑战页（内嵌 `register('/sw.js')` 与离线页预缓存），设置长过期 Cookie |
|
||||
| 带 Cookie 的请求 | 直接放行到上游，正常返回真实页面 |
|
||||
| 未知 UA（爬虫、curl，无真实浏览器特征） | 直接放过，交给 WAF 处理，拿到真实内容 |
|
||||
|
||||
### 为什么不用 sub_filter
|
||||
|
||||
`sub_filter` 需处理上游 gzip / Content-Type / 大响应扫描 / 流式缓冲等多处坑。本方案不改上游 body，整体替换首次响应，以上问题全部规避；且爬虫（不匹配真实浏览器 UA）天然绕过挑战页，不伤 SEO。
|
||||
|
||||
## 3. 分层职责
|
||||
|
||||
```
|
||||
apps/proxy_route ─┐
|
||||
apps/pages ─┼─ model → repository → 渲染(pkg/render/openresty) → Agent(OpenResty)
|
||||
前端设置卡 ─┘ ↑ SW 挑战页 + sw.js/offline 落盘
|
||||
```
|
||||
|
||||
### 后端数据（全局 Option，与 origin error page 同模式）
|
||||
|
||||
`sw_offline` 相关配置作为**全局 SystemConfig / OpenRestyConfig snapshot 字段**，对所有启用 HTTPS 的路由生效，实现"一键批量下发"。新增字段：
|
||||
|
||||
- `sw_offline_enabled`：是否启用 SW 离线兜底
|
||||
- `sw_offline_html`：联系站长离线页 HTML 内容（默认提供内置模板）
|
||||
|
||||
### 渲染层（`pkg/render/openresty`）
|
||||
|
||||
新增 `renderServiceWorkerChallenger(cfg ConfigSnapshot)` 工具，为真实提供内容的 HTTPS server 块（`sw_offline_enabled` 且 `EnableHTTPS` 时）输出：
|
||||
|
||||
```nginx
|
||||
# SW 脚本 + 离线页（作为 support file 落盘）
|
||||
location = /sw.js { alias .../sw.js; add_header Service-Worker-Allowed /; }
|
||||
location = /offline.html { alias .../offline.html; }
|
||||
|
||||
# 仅首页拦截：真实浏览器 UA 且无 cookie → 返回 SW 挑战页
|
||||
# 否则（带 cookie / 未知 UA）→ 放行到上游
|
||||
location = / {
|
||||
if (真实浏览器UA && 无cookie) { content_by_lua 返回 SW 挑战页; }
|
||||
放行到上游;
|
||||
}
|
||||
```
|
||||
|
||||
- SW 逻辑：`install` 阶段缓存 `/offline.html`；`fetch` 事件在网络失败时返回 `caches.match('/offline.html')`。
|
||||
- 仅在 `EnableHTTPS` 时注入（SW 要求 HTTPS 安全上下文）。
|
||||
- 多域名 server 块：`/sw.js`、`/offline.html`、挑战页在各 `server_name` 下同源可达。
|
||||
- 仅对首页 `location = /` 触发；js/css/图片/API/子页面请求不拦，零额外开销。
|
||||
|
||||
## 4. 数据流
|
||||
|
||||
```
|
||||
用户首次访问首页(真实UA, 无cookie)
|
||||
→ OpenResty 判断：真实UA && 无cookie
|
||||
→ 返回 SW 挑战页 (内嵌 register + 预缓存 offline.html)
|
||||
→ 浏览器执行 → 注册 SW → 设置长过期 cookie
|
||||
→ 用户再次请求(带cookie)
|
||||
→ 放行到上游，正常返回真实页面
|
||||
域名被墙后
|
||||
→ 所有请求失败 → SW fetch 兜底 → 从缓存返回 /offline.html(联系页)
|
||||
```
|
||||
|
||||
## 5. 边界与风险
|
||||
|
||||
| 项 | 处理 |
|
||||
|---|---|
|
||||
| 首次即被墙的用户 | SW 未注册，兜底无效（所有 SW 方案共性，接受） |
|
||||
| HTTP-only 站点 | 跳过注入（SW 需 HTTPS） |
|
||||
| 反代多域名 | 各域名同源提供 sw.js / offline.html / 挑战页 |
|
||||
| Cookie 过期 | 设长过期（约 1 年），过期后重新走一次挑战页 |
|
||||
| 未知 UA | 放过并交给 WAF 处理，不重复拦截 |
|
||||
| 资源/API 请求 | 不拦，仅首页触发 |
|
||||
|
||||
## 6. 测试
|
||||
|
||||
- 渲染层单元测试：
|
||||
- `sw_offline_enabled` 时输出 sw.js / offline.html / 挑战页 location
|
||||
- 非 HTTPS 或未启用时不输出
|
||||
- 仅首页触发，子路径/资源不触发
|
||||
- UA 判定：真实浏览器 / 爬虫 / curl 三种 UA 的放行分支。
|
||||
- Cookie 有无的放行分支。
|
||||
- 现有 config snapshot checksum / rebind 测试不回归。
|
||||
|
||||
## 7. 前端命名与入口
|
||||
|
||||
离线联系页设置与现有 origin error page 设置合并为同一个功能模块，命名为**「响应页面」**（路由 `responses`），内含两个 tab：
|
||||
|
||||
- **错误页设置**：源站错误兜底页（现有 origin error page）
|
||||
- **联系页设置**：SW 离线兜底联系页（本功能）
|
||||
|
||||
两者同属「边缘层兜底展示页」语义，统一管理与入口。
|
||||
|
||||
## 8. 待实现确认项（写 plan 时细化）
|
||||
|
||||
- SW 挑战页与 sw.js 的具体 Lua 实现与落盘路径（对齐现有 support file 机制）。
|
||||
- `sw_offline_html` 默认内置模板样式（参考 origin error page 内置模板）。
|
||||
- 「响应页面」前端模块下错误页/联系页两个 tab 的具体位置与交互。
|
||||
- UA 白名单默认真实浏览器特征集合（Chrome / Firefox / Safari / Edge + 版本号正则）。
|
||||
- SW 落盘路径：sw.js / offline.html 通过 SupportFile 下发，Agent 替换占位符（类似 ErrorPageTmplPlaceholder 机制）。
|
||||
@@ -0,0 +1,191 @@
|
||||
# SW 离线兜底生效范围（域名作用域）设计
|
||||
|
||||
- 日期：2026-08-08
|
||||
- 状态：设计已确认
|
||||
- 前置：issue #23 Service Worker 离线兜底（`docs/superpowers/specs/2026-08-08-service-worker-offline-design.md`）
|
||||
- 范围：SW 注入从「全局所有 HTTPS 站点」细化为「总开关 + 域名作用域」
|
||||
|
||||
## 1. 背景与目标
|
||||
|
||||
issue #23 实现后，`sw_offline_enabled` 为全局布尔开关：开启后对所有启用 HTTPS 的路由注入 Service Worker 离线兜底。本需求将其细化为可选的**生效域名范围**：
|
||||
|
||||
- 保留总开关（`sw_offline_enabled`）。
|
||||
- 新增作用域：管理员选择需要生效的域名，仅作用域内域名注入 SW。
|
||||
- 域名选择交互参考 `/cloudflare/groups/1` 的「添加域名成员」弹窗（搜索筛选、按 Zone 分组、批量勾选），但**与 Cloudflare 完全解耦**——仅复用交互模式，数据源为平台自身 zones/zone_domains，不涉及 A 记录同步。
|
||||
|
||||
核心约束：
|
||||
|
||||
- 语义为「总开关 && 域名 ∈ 作用域」交集：总开关关 → 全部不注入；总开关开 + 作用域空 → 不注入；总开关开 + 域名命中 → 注入。
|
||||
- 与 Cloudflare 指向分组（A 记录）无任何关联。
|
||||
- 联系页 HTML（`sw_offline_html`）仍为全局单份，不分域名定制。
|
||||
|
||||
## 2. 机制总览
|
||||
|
||||
```
|
||||
sw_offline_enabled (bool, 已有) 总开关
|
||||
sw_offline_html (string, 已有) 联系页 HTML（全局一份）
|
||||
sw_offline_domains (JSON 字符串数组, 新增) 生效域名作用域
|
||||
|
||||
渲染: routeSWEnabled(routeDomains, cfg)
|
||||
= SWOfflineEnabled && routeDomains ∩ SWOfflineDomains ≠ ∅
|
||||
命中 → HTTPS server 块注入 access 检查 + SW location
|
||||
未命中 → 与 feature 前字节一致
|
||||
```
|
||||
|
||||
Support files（`sw/sw.js`、`sw/offline.html`）仅在「总开关开 && 作用域非空」时下发，避免空作用域产生无用资源。
|
||||
|
||||
## 3. 数据层
|
||||
|
||||
### 3.1 配置 key
|
||||
|
||||
`model.ConfigKeySWOfflineDomains = "sw_offline_domains"`（business 类型，visibility 0），值存 JSON 域名字符串数组：
|
||||
|
||||
```json
|
||||
["example.com", "api.example.com"]
|
||||
```
|
||||
|
||||
### 3.2 goose 迁移（postgres + sqlite 各一份）
|
||||
|
||||
`INSERT INTO w_system_configs (key, value, type, visibility, description, created_at, updated_at) VALUES ('sw_offline_domains', '[]', 'business', 0, 'SW 离线兜底生效域名列表（JSON 数组，空则仅总开关无效）', CURRENT_TIMESTAMP, CURRENT_TIMESTAMP) ON CONFLICT (key) DO NOTHING;`
|
||||
|
||||
Down 删除该 key。migrator 测试计数 92 → 93，并更新注释。
|
||||
|
||||
### 3.3 validator
|
||||
|
||||
`validateSWOfflineDomains(key, value string) error`，注册进 `openRestyOptionValidators`：
|
||||
|
||||
- JSON 解析为 `[]string`，失败报「必须为 JSON 字符串数组」
|
||||
- 元素去重（重复报错）
|
||||
- 元素非空、小写规范化校验（复用/对齐 zone `normalizeDomain` 的域名格式约束：无 `*`、无 `://` `/` `?` `#` `@`、`publicsuffix.EffectiveTLDPlusOne` 可解析）
|
||||
- 数量上限 `maxSWOfflineDomains = 1000`（防滥用）
|
||||
|
||||
### 3.4 config_version snapshot
|
||||
|
||||
- `openRestyConfigSnapshot`（`snapshot.go`）新增 `SWOfflineDomains []string json:"sw_offline_domains,omitempty"`。
|
||||
- `buildOpenRestyConfigSnapshot` 新增 `getStringSliceConfig(key string, defaultVal []string) []string`（解析 JSON 数组，失败回退默认），赋值 `SWOfflineDomains: getStringSliceConfig(model.ConfigKeySWOfflineDomains, nil)`。
|
||||
- `logics.go`：`diffOpenRestyOptionDetails` 追加 `appendIfChanged("SWOfflineDomains", ...)`；`openRestyOptionKeys()` 追加 `"SWOfflineDomains"`。
|
||||
|
||||
## 4. 渲染层（pkg/render/openresty）
|
||||
|
||||
### 4.1 ConfigSnapshot
|
||||
|
||||
`types.go` 的 `ConfigSnapshot` 新增：
|
||||
|
||||
```go
|
||||
// SWOfflineDomains restricts the offline fallback to matching HTTPS routes.
|
||||
SWOfflineDomains []string `json:"sw_offline_domains,omitempty"`
|
||||
```
|
||||
|
||||
### 4.2 作用域判断
|
||||
|
||||
```go
|
||||
// routeSWEnabled returns true when SW offline fallback applies to this route.
|
||||
func routeSWEnabled(routeDomains []string, cfg ConfigSnapshot) bool {
|
||||
if !cfg.SWOfflineEnabled || len(cfg.SWOfflineDomains) == 0 {
|
||||
return false
|
||||
}
|
||||
scope := make(map[string]struct{}, len(cfg.SWOfflineDomains))
|
||||
for _, d := range cfg.SWOfflineDomains {
|
||||
scope[d] = struct{}{}
|
||||
}
|
||||
for _, d := range routeDomains {
|
||||
if _, ok := scope[d]; ok {
|
||||
return true
|
||||
}
|
||||
}
|
||||
return false
|
||||
}
|
||||
```
|
||||
|
||||
域名精确匹配（存储时已小写规范化）。
|
||||
|
||||
### 4.3 server 渲染签名扩展
|
||||
|
||||
- `RenderRouteConfig`：每 route 计算 `swEnabled := routeSWEnabled(domains, doc.OpenRestyConfig)`，传入 `renderProxyRoute` / `renderPagesRoute`（新增 `swEnabled bool` 参数）。
|
||||
- 下传链路：`renderProxyRouteHTTPS` / `renderPagesRouteHTTPS` / `renderHTTPSServer` / `renderHTTPSPagesServer` 均新增 `swEnabled bool` 参数。
|
||||
- `swEnabled=true` → `renderAccessBlockWithSW(siteName, powEnabled, cfg)` + 追加 `renderServiceWorkerChallenger(cfg)`（现行为，两函数内部不再判断 `SWOfflineEnabled`，条件已上移到 route 层）。
|
||||
- `swEnabled=false` → 纯 `renderAccessBlock`，无 challenger（与 feature 前字节一致）。
|
||||
- HTTP（80）server 块保持不注入（issue #23 已定 HTTPS-only）。
|
||||
- `renderAccessBlockWithSW` / `renderServiceWorkerChallenger` 保留 `cfg` 参数（HTML 内容来自 `cfg.SWOfflineHTML`），仅移除其内部开关判断。
|
||||
|
||||
### 4.4 Support files
|
||||
|
||||
`Render` 中生成条件从 `if doc.OpenRestyConfig.SWOfflineEnabled` 改为：
|
||||
|
||||
```go
|
||||
if doc.OpenRestyConfig.SWOfflineEnabled && len(doc.OpenRestyConfig.SWOfflineDomains) > 0 {
|
||||
files = append(files, ServiceWorkerSupportFiles(doc.OpenRestyConfig)...)
|
||||
}
|
||||
```
|
||||
|
||||
### 4.5 测试
|
||||
|
||||
- `routeSWEnabled`：开关关 / 作用域空 / 无交集 / 单域名交集 / 多域名部分交集。
|
||||
- HTTPS server 渲染：命中 → 含 `require("sw.runtime").check()` + 三个 SW location；未命中 → 与旧输出字节一致。
|
||||
- `Render`：空作用域不下发 `sw/*` support files。
|
||||
- 现有 `TestRenderAccessBlockWithSWMergesSingleBlock` 等适配新签名（`cfg` 语义变化：禁用时不再由内部判断，改由上层传 `swEnabled`）。
|
||||
|
||||
## 5. 前端（frontend/app/(main)/responses）
|
||||
|
||||
### 5.1 联系页 tab 布局
|
||||
|
||||
联系页 tab 两张卡片：
|
||||
|
||||
**卡片 1：离线兜底（总开关）**
|
||||
- 标题「离线兜底」+ 描述。
|
||||
- 右上角「保存」按钮。
|
||||
- 「启用 Service Worker 离线兜底」Switch（`sw_offline_enabled`）。
|
||||
- 「生效范围」区块：当前已选域名 badge 列表（可移除）+「添加域名」按钮打开弹窗；开关关闭时整卡禁用/置灰。
|
||||
- 保存时 `updateBatch` 一次性提交三个 key：
|
||||
```ts
|
||||
{ key: KEY_SW_ENABLED, value: String(fields.enabled) },
|
||||
{ key: KEY_SW_HTML, value: fields.html },
|
||||
{ key: KEY_SW_DOMAINS, value: JSON.stringify(fields.domains) },
|
||||
```
|
||||
- 保存成功后 `invalidateResponseQueries`（toast 提示「请前往版本发布使配置生效」不变）。
|
||||
|
||||
**卡片 2：联系页 HTML**
|
||||
- 复用 `HtmlEditorWorkspace`（见 5.3），无占位符，实时预览原样 HTML。
|
||||
|
||||
### 5.2 域名选择弹窗（scope-domain-dialog.tsx）
|
||||
|
||||
- 交互复用 `member-add-dialog.tsx`：搜索框（域名/zone 模糊匹配）、按 Zone 分组折叠、组内勾选/取消、全选可见/清空、已选计数。
|
||||
- 无橙云开关、无 Cloudflare 依赖。
|
||||
- 数据源：`ZoneService.list()` + 每 zone `ZoneService.getOverview(id)` 并行拉取（`Promise.all`），zone 根域并入对应分组。**不新增后端 API**。
|
||||
- 弹窗预勾选当前已生效域名；确认后返回选中的域名字符串数组（覆盖式替换本地 fields.domains）。
|
||||
- 空态：无 zone 时提示「暂无可用域名，请先在 Zone 管理中注册」。
|
||||
|
||||
### 5.3 HtmlEditorWorkspace 复用（泛化）
|
||||
|
||||
`frontend/app/(main)/error-pages/components/html-editor-workspace.tsx` 泛化并移至 `frontend/components/common/html-editor-workspace.tsx`：
|
||||
|
||||
- Props 扩展：
|
||||
- `maxBytes?: number`（默认 `ORIGIN_ERROR_PAGE_HTML_MAX_BYTES` = 256 KiB，SW 同为 256 KiB 常量可共用）
|
||||
- `preview?: (html: string) => string`（默认 `previewOriginErrorPageHTML`；SW 传 `(html) => html` 原样预览）
|
||||
- `footerHint?: React.ReactNode`（预览 footer 提示文案，默认错误页的「`{{status}}`→502 · `{{host}}`→example.com」；SW 传 `null`）
|
||||
- 错误页 `edit/page.tsx` 改 import 路径，行为不变。
|
||||
- `frontend/components/common/` 若不存在则创建目录。
|
||||
|
||||
### 5.4 shared.ts 与表单
|
||||
|
||||
- `KEY_SW_DOMAINS = 'sw_offline_domains'`。
|
||||
- `ContactPageFields` 增加 `domains: string[]`；`defaultContactPageFields.domains = []`。
|
||||
- `mapOptionsToContactFields` 解析 `sw_offline_domains` JSON（容错：非法 JSON → `[]`）。
|
||||
|
||||
## 6. 验证
|
||||
|
||||
- 后端：`go test ./pkg/render/openresty/... ./internal/apps/openflare/option/... ./internal/apps/openflare/config_version/... ./internal/infra/persistence/migrator/...`
|
||||
- 前端：`pnpm tsc --noEmit` + `eslint`（联系页新字段/弹窗/多 zone 并行拉取）
|
||||
- 全量：`go test ./...`、`make code-check`、`make format`
|
||||
- `make swagger`：无新 API（验证无变更即可）
|
||||
|
||||
## 7. Changelog
|
||||
|
||||
`docs/changelog/index.md` `[Unreleased]` 更新 SW 条目：新增「可指定生效域名范围（仅对选中的 HTTPS 域名生效）」。
|
||||
|
||||
## 8. 已知边界
|
||||
|
||||
- 作用域存域名字符串数组：域名从 zone/zone_domain 改名后需手动同步作用域（与 `route.Domains` 精确匹配）。
|
||||
- 联系页 HTML 全局单份，不分域名定制。
|
||||
- 空作用域 + 总开关开 → 不注入（前端置灰提示先选域名）。
|
||||
- 匹配为精确匹配，不跨子域通配（选 `example.com` 不自动覆盖 `api.example.com`，需显式加入）。
|
||||
+108
-168
@@ -1017,7 +1017,7 @@
|
||||
"SessionCookie": []
|
||||
}
|
||||
],
|
||||
"description": "分页并按照用户、接口路径、时间范围等维度检索 ClickHouse 用户访问日志列表（需要管理员权限，ClickHouse 未启用时报错）",
|
||||
"description": "分页并按照用户、接口路径、时间范围等维度检索用户访问日志列表（需要管理员权限，日志存储未启用时报错）",
|
||||
"produces": [
|
||||
"application/json"
|
||||
],
|
||||
@@ -1085,7 +1085,7 @@
|
||||
}
|
||||
},
|
||||
"400": {
|
||||
"description": "ClickHouse 未启用或参数错误",
|
||||
"description": "日志存储未启用或参数错误",
|
||||
"schema": {
|
||||
"$ref": "#/definitions/response.Any"
|
||||
}
|
||||
@@ -1112,7 +1112,7 @@
|
||||
"SessionCookie": []
|
||||
}
|
||||
],
|
||||
"description": "聚合统计最近 7 天的每日访问趋势、浏览器分布以及前 10 名最活跃用户排行（需要管理员权限，ClickHouse 未启用时报错）",
|
||||
"description": "聚合统计最近 7 天的每日访问趋势、浏览器分布以及前 10 名最活跃用户排行（需要管理员权限，日志存储未启用时报错）",
|
||||
"produces": [
|
||||
"application/json"
|
||||
],
|
||||
@@ -1140,7 +1140,7 @@
|
||||
}
|
||||
},
|
||||
"400": {
|
||||
"description": "ClickHouse 未启用",
|
||||
"description": "日志存储未启用",
|
||||
"schema": {
|
||||
"$ref": "#/definitions/response.Any"
|
||||
}
|
||||
@@ -1870,21 +1870,21 @@
|
||||
}
|
||||
}
|
||||
},
|
||||
"/api/v1/admin/status/clickhouse": {
|
||||
"/api/v1/admin/status/log-database": {
|
||||
"get": {
|
||||
"security": [
|
||||
{
|
||||
"SessionCookie": []
|
||||
}
|
||||
],
|
||||
"description": "返回 ClickHouse parts、mutation、async_insert 队列及进程内 batch writer 指标，需要管理员权限",
|
||||
"description": "返回当前日志主库、迁移状态、各库保留天数与合法迁移目标，需要管理员权限",
|
||||
"produces": [
|
||||
"application/json"
|
||||
],
|
||||
"tags": [
|
||||
"admin"
|
||||
],
|
||||
"summary": "获取 ClickHouse 运行指标",
|
||||
"summary": "获取日志数据库状态",
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "获取成功",
|
||||
@@ -1897,19 +1897,13 @@
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"data": {
|
||||
"$ref": "#/definitions/analytics.ClickHouseOperationalStats"
|
||||
"$ref": "#/definitions/status.LogDatabaseStatus"
|
||||
}
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
},
|
||||
"400": {
|
||||
"description": "ClickHouse 未启用",
|
||||
"schema": {
|
||||
"$ref": "#/definitions/response.Any"
|
||||
}
|
||||
},
|
||||
"401": {
|
||||
"description": "未登录",
|
||||
"schema": {
|
||||
@@ -2386,6 +2380,18 @@
|
||||
"name": "task_type",
|
||||
"in": "query"
|
||||
},
|
||||
{
|
||||
"type": "string",
|
||||
"description": "任务类型前缀筛选（与 task_type / task_types 互斥，精确类型优先）",
|
||||
"name": "task_type_prefix",
|
||||
"in": "query"
|
||||
},
|
||||
{
|
||||
"type": "string",
|
||||
"description": "逗号分隔的精确任务类型列表（IN 筛选，优先于前缀）",
|
||||
"name": "task_types",
|
||||
"in": "query"
|
||||
},
|
||||
{
|
||||
"type": "integer",
|
||||
"default": 1,
|
||||
@@ -4796,7 +4802,7 @@
|
||||
"SessionCookie": []
|
||||
}
|
||||
],
|
||||
"description": "分页返回 OpenFlare 访问日志，支持按节点、IP、主机与路径筛选，需要管理员权限",
|
||||
"description": "分页返回 OpenFlare 访问日志，支持按节点、IP、主机、路径与状态码筛选，需要管理员权限",
|
||||
"produces": [
|
||||
"application/json"
|
||||
],
|
||||
@@ -4829,6 +4835,24 @@
|
||||
"name": "path",
|
||||
"in": "query"
|
||||
},
|
||||
{
|
||||
"type": "integer",
|
||||
"description": "HTTP 状态码（100-599）",
|
||||
"name": "status_code",
|
||||
"in": "query"
|
||||
},
|
||||
{
|
||||
"type": "string",
|
||||
"description": "起始时间（RFC3339，需与 until 成对提供）",
|
||||
"name": "since",
|
||||
"in": "query"
|
||||
},
|
||||
{
|
||||
"type": "string",
|
||||
"description": "结束时间（RFC3339，需与 since 成对提供）",
|
||||
"name": "until",
|
||||
"in": "query"
|
||||
},
|
||||
{
|
||||
"type": "integer",
|
||||
"description": "页码",
|
||||
@@ -8298,80 +8322,6 @@
|
||||
}
|
||||
}
|
||||
},
|
||||
"/api/v1/d/option/database/cleanup": {
|
||||
"post": {
|
||||
"security": [
|
||||
{
|
||||
"SessionCookie": []
|
||||
}
|
||||
],
|
||||
"description": "按目标与保留天数清理可观测性相关数据表，需要管理员权限",
|
||||
"consumes": [
|
||||
"application/json"
|
||||
],
|
||||
"produces": [
|
||||
"application/json"
|
||||
],
|
||||
"tags": [
|
||||
"openflare-option"
|
||||
],
|
||||
"summary": "清理可观测性数据库",
|
||||
"parameters": [
|
||||
{
|
||||
"description": "清理参数",
|
||||
"name": "request",
|
||||
"in": "body",
|
||||
"schema": {
|
||||
"$ref": "#/definitions/option.databaseCleanupInput"
|
||||
}
|
||||
}
|
||||
],
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "清理结果",
|
||||
"schema": {
|
||||
"allOf": [
|
||||
{
|
||||
"$ref": "#/definitions/response.Any"
|
||||
},
|
||||
{
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"data": {
|
||||
"$ref": "#/definitions/option.databaseCleanupResult"
|
||||
}
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
},
|
||||
"400": {
|
||||
"description": "参数错误",
|
||||
"schema": {
|
||||
"$ref": "#/definitions/response.Any"
|
||||
}
|
||||
},
|
||||
"401": {
|
||||
"description": "未登录",
|
||||
"schema": {
|
||||
"$ref": "#/definitions/response.Any"
|
||||
}
|
||||
},
|
||||
"404": {
|
||||
"description": "无权限或不存在",
|
||||
"schema": {
|
||||
"$ref": "#/definitions/response.Any"
|
||||
}
|
||||
},
|
||||
"500": {
|
||||
"description": "内部错误",
|
||||
"schema": {
|
||||
"$ref": "#/definitions/response.Any"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"/api/v1/d/option/geoip/lookup": {
|
||||
"post": {
|
||||
"security": [
|
||||
@@ -14899,33 +14849,26 @@
|
||||
}
|
||||
}
|
||||
},
|
||||
"analytics.ClickHouseOperationalStats": {
|
||||
"analytics.BatchWriterStats": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"active_parts": {
|
||||
"cap": {
|
||||
"type": "integer"
|
||||
},
|
||||
"async_insert_bytes": {
|
||||
"depth": {
|
||||
"type": "integer"
|
||||
},
|
||||
"async_insert_queue": {
|
||||
"drops": {
|
||||
"type": "integer"
|
||||
},
|
||||
"batch_writers": {
|
||||
"description": "BatchWriters reports in-process queue depth/drops/flush errors for CH writers.",
|
||||
"type": "array",
|
||||
"items": {
|
||||
"$ref": "#/definitions/batchwriter.Stats"
|
||||
}
|
||||
"flush_errors": {
|
||||
"type": "integer"
|
||||
},
|
||||
"database": {
|
||||
"name": {
|
||||
"type": "string"
|
||||
},
|
||||
"pending_mutations": {
|
||||
"type": "integer"
|
||||
},
|
||||
"total_rows": {
|
||||
"type": "integer"
|
||||
"running": {
|
||||
"type": "boolean"
|
||||
}
|
||||
}
|
||||
},
|
||||
@@ -15017,29 +14960,6 @@
|
||||
}
|
||||
}
|
||||
},
|
||||
"batchwriter.Stats": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"cap": {
|
||||
"type": "integer"
|
||||
},
|
||||
"depth": {
|
||||
"type": "integer"
|
||||
},
|
||||
"drops": {
|
||||
"type": "integer"
|
||||
},
|
||||
"flush_errors": {
|
||||
"type": "integer"
|
||||
},
|
||||
"name": {
|
||||
"type": "string"
|
||||
},
|
||||
"running": {
|
||||
"type": "boolean"
|
||||
}
|
||||
}
|
||||
},
|
||||
"cache.updateCacheConfigRequest": {
|
||||
"type": "object",
|
||||
"required": [
|
||||
@@ -15098,6 +15018,9 @@
|
||||
"id": {
|
||||
"type": "integer"
|
||||
},
|
||||
"zone_domain": {
|
||||
"type": "string"
|
||||
},
|
||||
"zone_id": {
|
||||
"type": "integer"
|
||||
}
|
||||
@@ -15819,6 +15742,36 @@
|
||||
}
|
||||
}
|
||||
},
|
||||
"github_com_Rain-kl_Wavelet_internal_model_analytics.ClickHouseOperationalStats": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"active_parts": {
|
||||
"type": "integer"
|
||||
},
|
||||
"async_insert_bytes": {
|
||||
"type": "integer"
|
||||
},
|
||||
"async_insert_queue": {
|
||||
"type": "integer"
|
||||
},
|
||||
"batch_writers": {
|
||||
"description": "BatchWriters reports in-process queue depth/drops/flush errors for CH writers.",
|
||||
"type": "array",
|
||||
"items": {
|
||||
"$ref": "#/definitions/analytics.BatchWriterStats"
|
||||
}
|
||||
},
|
||||
"database": {
|
||||
"type": "string"
|
||||
},
|
||||
"pending_mutations": {
|
||||
"type": "integer"
|
||||
},
|
||||
"total_rows": {
|
||||
"type": "integer"
|
||||
}
|
||||
}
|
||||
},
|
||||
"github_com_Rain-kl_Wavelet_pkg_protocol.ActiveConfigMeta": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
@@ -18474,46 +18427,6 @@
|
||||
}
|
||||
}
|
||||
},
|
||||
"option.databaseCleanupInput": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"retention_days": {
|
||||
"type": "integer"
|
||||
},
|
||||
"target": {
|
||||
"type": "string"
|
||||
}
|
||||
}
|
||||
},
|
||||
"option.databaseCleanupResult": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"cleanup_mode": {
|
||||
"type": "string"
|
||||
},
|
||||
"delete_all": {
|
||||
"type": "boolean"
|
||||
},
|
||||
"deleted_count": {
|
||||
"type": "integer"
|
||||
},
|
||||
"eligible_count": {
|
||||
"type": "integer"
|
||||
},
|
||||
"retention_days": {
|
||||
"type": "integer"
|
||||
},
|
||||
"table_ttl_days": {
|
||||
"type": "integer"
|
||||
},
|
||||
"target": {
|
||||
"type": "string"
|
||||
},
|
||||
"target_label": {
|
||||
"type": "string"
|
||||
}
|
||||
}
|
||||
},
|
||||
"option.geoIPLookupRequest": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
@@ -19852,6 +19765,33 @@
|
||||
}
|
||||
}
|
||||
},
|
||||
"status.LogDatabaseStatus": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"active_database": {
|
||||
"type": "string"
|
||||
},
|
||||
"available_targets": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "string"
|
||||
}
|
||||
},
|
||||
"clickhouse": {
|
||||
"$ref": "#/definitions/github_com_Rain-kl_Wavelet_internal_model_analytics.ClickHouseOperationalStats"
|
||||
},
|
||||
"migration": {
|
||||
"description": "idle | migrating",
|
||||
"type": "string"
|
||||
},
|
||||
"retention_days": {
|
||||
"type": "object",
|
||||
"additionalProperties": {
|
||||
"type": "integer"
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"status.SystemStatusResponse": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
|
||||
+79
-113
@@ -169,26 +169,20 @@ definitions:
|
||||
$ref: '#/definitions/github_com_Rain-kl_Wavelet_pkg_protocol.WAFIPGroup'
|
||||
type: array
|
||||
type: object
|
||||
analytics.ClickHouseOperationalStats:
|
||||
analytics.BatchWriterStats:
|
||||
properties:
|
||||
active_parts:
|
||||
cap:
|
||||
type: integer
|
||||
async_insert_bytes:
|
||||
depth:
|
||||
type: integer
|
||||
async_insert_queue:
|
||||
drops:
|
||||
type: integer
|
||||
batch_writers:
|
||||
description: BatchWriters reports in-process queue depth/drops/flush errors
|
||||
for CH writers.
|
||||
items:
|
||||
$ref: '#/definitions/batchwriter.Stats'
|
||||
type: array
|
||||
database:
|
||||
flush_errors:
|
||||
type: integer
|
||||
name:
|
||||
type: string
|
||||
pending_mutations:
|
||||
type: integer
|
||||
total_rows:
|
||||
type: integer
|
||||
running:
|
||||
type: boolean
|
||||
type: object
|
||||
apply_log.CleanupInput:
|
||||
properties:
|
||||
@@ -247,21 +241,6 @@ definitions:
|
||||
is_active:
|
||||
type: boolean
|
||||
type: object
|
||||
batchwriter.Stats:
|
||||
properties:
|
||||
cap:
|
||||
type: integer
|
||||
depth:
|
||||
type: integer
|
||||
drops:
|
||||
type: integer
|
||||
flush_errors:
|
||||
type: integer
|
||||
name:
|
||||
type: string
|
||||
running:
|
||||
type: boolean
|
||||
type: object
|
||||
cache.updateCacheConfigRequest:
|
||||
properties:
|
||||
lru_enabled:
|
||||
@@ -301,6 +280,8 @@ definitions:
|
||||
type: string
|
||||
id:
|
||||
type: integer
|
||||
zone_domain:
|
||||
type: string
|
||||
zone_id:
|
||||
type: integer
|
||||
type: object
|
||||
@@ -774,6 +755,27 @@ definitions:
|
||||
token:
|
||||
type: string
|
||||
type: object
|
||||
github_com_Rain-kl_Wavelet_internal_model_analytics.ClickHouseOperationalStats:
|
||||
properties:
|
||||
active_parts:
|
||||
type: integer
|
||||
async_insert_bytes:
|
||||
type: integer
|
||||
async_insert_queue:
|
||||
type: integer
|
||||
batch_writers:
|
||||
description: BatchWriters reports in-process queue depth/drops/flush errors
|
||||
for CH writers.
|
||||
items:
|
||||
$ref: '#/definitions/analytics.BatchWriterStats'
|
||||
type: array
|
||||
database:
|
||||
type: string
|
||||
pending_mutations:
|
||||
type: integer
|
||||
total_rows:
|
||||
type: integer
|
||||
type: object
|
||||
github_com_Rain-kl_Wavelet_pkg_protocol.ActiveConfigMeta:
|
||||
properties:
|
||||
checksum:
|
||||
@@ -2533,32 +2535,6 @@ definitions:
|
||||
window_started_at:
|
||||
type: string
|
||||
type: object
|
||||
option.databaseCleanupInput:
|
||||
properties:
|
||||
retention_days:
|
||||
type: integer
|
||||
target:
|
||||
type: string
|
||||
type: object
|
||||
option.databaseCleanupResult:
|
||||
properties:
|
||||
cleanup_mode:
|
||||
type: string
|
||||
delete_all:
|
||||
type: boolean
|
||||
deleted_count:
|
||||
type: integer
|
||||
eligible_count:
|
||||
type: integer
|
||||
retention_days:
|
||||
type: integer
|
||||
table_ttl_days:
|
||||
type: integer
|
||||
target:
|
||||
type: string
|
||||
target_label:
|
||||
type: string
|
||||
type: object
|
||||
option.geoIPLookupRequest:
|
||||
properties:
|
||||
ip:
|
||||
@@ -3442,6 +3418,24 @@ definitions:
|
||||
version:
|
||||
type: string
|
||||
type: object
|
||||
status.LogDatabaseStatus:
|
||||
properties:
|
||||
active_database:
|
||||
type: string
|
||||
available_targets:
|
||||
items:
|
||||
type: string
|
||||
type: array
|
||||
clickhouse:
|
||||
$ref: '#/definitions/github_com_Rain-kl_Wavelet_internal_model_analytics.ClickHouseOperationalStats'
|
||||
migration:
|
||||
description: idle | migrating
|
||||
type: string
|
||||
retention_days:
|
||||
additionalProperties:
|
||||
type: integer
|
||||
type: object
|
||||
type: object
|
||||
status.SystemStatusResponse:
|
||||
properties:
|
||||
alloc:
|
||||
@@ -4935,7 +4929,7 @@ paths:
|
||||
- admin
|
||||
/api/v1/admin/logs/access:
|
||||
get:
|
||||
description: 分页并按照用户、接口路径、时间范围等维度检索 ClickHouse 用户访问日志列表（需要管理员权限，ClickHouse 未启用时报错）
|
||||
description: 分页并按照用户、接口路径、时间范围等维度检索用户访问日志列表（需要管理员权限，日志存储未启用时报错）
|
||||
parameters:
|
||||
- default: 1
|
||||
description: 页码
|
||||
@@ -4976,7 +4970,7 @@ paths:
|
||||
$ref: '#/definitions/logs.accessLogsResponse'
|
||||
type: object
|
||||
"400":
|
||||
description: ClickHouse 未启用或参数错误
|
||||
description: 日志存储未启用或参数错误
|
||||
schema:
|
||||
$ref: '#/definitions/response.Any'
|
||||
"401":
|
||||
@@ -4994,7 +4988,7 @@ paths:
|
||||
- admin
|
||||
/api/v1/admin/logs/analytics:
|
||||
get:
|
||||
description: 聚合统计最近 7 天的每日访问趋势、浏览器分布以及前 10 名最活跃用户排行（需要管理员权限，ClickHouse 未启用时报错）
|
||||
description: 聚合统计最近 7 天的每日访问趋势、浏览器分布以及前 10 名最活跃用户排行（需要管理员权限，日志存储未启用时报错）
|
||||
produces:
|
||||
- application/json
|
||||
responses:
|
||||
@@ -5008,7 +5002,7 @@ paths:
|
||||
$ref: '#/definitions/logs.logsAnalyticsResponse'
|
||||
type: object
|
||||
"400":
|
||||
description: ClickHouse 未启用
|
||||
description: 日志存储未启用
|
||||
schema:
|
||||
$ref: '#/definitions/response.Any'
|
||||
"401":
|
||||
@@ -5434,9 +5428,9 @@ paths:
|
||||
summary: 获取系统状态信息
|
||||
tags:
|
||||
- admin
|
||||
/api/v1/admin/status/clickhouse:
|
||||
/api/v1/admin/status/log-database:
|
||||
get:
|
||||
description: 返回 ClickHouse parts、mutation、async_insert 队列及进程内 batch writer 指标，需要管理员权限
|
||||
description: 返回当前日志主库、迁移状态、各库保留天数与合法迁移目标，需要管理员权限
|
||||
produces:
|
||||
- application/json
|
||||
responses:
|
||||
@@ -5447,12 +5441,8 @@ paths:
|
||||
- $ref: '#/definitions/response.Any'
|
||||
- properties:
|
||||
data:
|
||||
$ref: '#/definitions/analytics.ClickHouseOperationalStats'
|
||||
$ref: '#/definitions/status.LogDatabaseStatus'
|
||||
type: object
|
||||
"400":
|
||||
description: ClickHouse 未启用
|
||||
schema:
|
||||
$ref: '#/definitions/response.Any'
|
||||
"401":
|
||||
description: 未登录
|
||||
schema:
|
||||
@@ -5467,7 +5457,7 @@ paths:
|
||||
$ref: '#/definitions/response.Any'
|
||||
security:
|
||||
- SessionCookie: []
|
||||
summary: 获取 ClickHouse 运行指标
|
||||
summary: 获取日志数据库状态
|
||||
tags:
|
||||
- admin
|
||||
/api/v1/admin/system-configs:
|
||||
@@ -5738,6 +5728,14 @@ paths:
|
||||
in: query
|
||||
name: task_type
|
||||
type: string
|
||||
- description: 任务类型前缀筛选（与 task_type / task_types 互斥，精确类型优先）
|
||||
in: query
|
||||
name: task_type_prefix
|
||||
type: string
|
||||
- description: 逗号分隔的精确任务类型列表（IN 筛选，优先于前缀）
|
||||
in: query
|
||||
name: task_types
|
||||
type: string
|
||||
- default: 1
|
||||
description: 页码
|
||||
in: query
|
||||
@@ -7196,7 +7194,7 @@ paths:
|
||||
- config
|
||||
/api/v1/d/access-logs:
|
||||
get:
|
||||
description: 分页返回 OpenFlare 访问日志，支持按节点、IP、主机与路径筛选，需要管理员权限
|
||||
description: 分页返回 OpenFlare 访问日志，支持按节点、IP、主机、路径与状态码筛选，需要管理员权限
|
||||
parameters:
|
||||
- description: 节点 ID
|
||||
in: query
|
||||
@@ -7214,6 +7212,18 @@ paths:
|
||||
in: query
|
||||
name: path
|
||||
type: string
|
||||
- description: HTTP 状态码（100-599）
|
||||
in: query
|
||||
name: status_code
|
||||
type: integer
|
||||
- description: 起始时间（RFC3339，需与 until 成对提供）
|
||||
in: query
|
||||
name: since
|
||||
type: string
|
||||
- description: 结束时间（RFC3339，需与 since 成对提供）
|
||||
in: query
|
||||
name: until
|
||||
type: string
|
||||
- description: 页码
|
||||
in: query
|
||||
name: p
|
||||
@@ -9285,50 +9295,6 @@ paths:
|
||||
summary: 列出 OpenFlare 配置项
|
||||
tags:
|
||||
- openflare-option
|
||||
/api/v1/d/option/database/cleanup:
|
||||
post:
|
||||
consumes:
|
||||
- application/json
|
||||
description: 按目标与保留天数清理可观测性相关数据表，需要管理员权限
|
||||
parameters:
|
||||
- description: 清理参数
|
||||
in: body
|
||||
name: request
|
||||
schema:
|
||||
$ref: '#/definitions/option.databaseCleanupInput'
|
||||
produces:
|
||||
- application/json
|
||||
responses:
|
||||
"200":
|
||||
description: 清理结果
|
||||
schema:
|
||||
allOf:
|
||||
- $ref: '#/definitions/response.Any'
|
||||
- properties:
|
||||
data:
|
||||
$ref: '#/definitions/option.databaseCleanupResult'
|
||||
type: object
|
||||
"400":
|
||||
description: 参数错误
|
||||
schema:
|
||||
$ref: '#/definitions/response.Any'
|
||||
"401":
|
||||
description: 未登录
|
||||
schema:
|
||||
$ref: '#/definitions/response.Any'
|
||||
"404":
|
||||
description: 无权限或不存在
|
||||
schema:
|
||||
$ref: '#/definitions/response.Any'
|
||||
"500":
|
||||
description: 内部错误
|
||||
schema:
|
||||
$ref: '#/definitions/response.Any'
|
||||
security:
|
||||
- SessionCookie: []
|
||||
summary: 清理可观测性数据库
|
||||
tags:
|
||||
- openflare-option
|
||||
/api/v1/d/option/geoip/lookup:
|
||||
post:
|
||||
consumes:
|
||||
|
||||
@@ -1,9 +1,22 @@
|
||||
'use client';
|
||||
|
||||
import { Search } from 'lucide-react';
|
||||
import { useState } from 'react';
|
||||
import { format } from 'date-fns';
|
||||
import { CalendarIcon, ChevronDown, Search } from 'lucide-react';
|
||||
|
||||
import { Button } from '@/components/ui/button';
|
||||
import { Calendar } from '@/components/ui/calendar';
|
||||
import {
|
||||
Collapsible,
|
||||
CollapsibleContent,
|
||||
CollapsibleTrigger,
|
||||
} from '@/components/ui/collapsible';
|
||||
import { Input } from '@/components/ui/input';
|
||||
import {
|
||||
Popover,
|
||||
PopoverContent,
|
||||
PopoverTrigger,
|
||||
} from '@/components/ui/popover';
|
||||
import {
|
||||
Select,
|
||||
SelectContent,
|
||||
@@ -23,6 +36,115 @@ interface AccessLogFiltersProps {
|
||||
onReset: () => void;
|
||||
}
|
||||
|
||||
const HOUR_OPTIONS = Array.from({ length: 24 }, (_, i) =>
|
||||
String(i).padStart(2, '0'),
|
||||
);
|
||||
const MINUTE_OPTIONS = Array.from({ length: 60 }, (_, i) =>
|
||||
String(i).padStart(2, '0'),
|
||||
);
|
||||
|
||||
function FilterField({
|
||||
label,
|
||||
children,
|
||||
}: {
|
||||
label: string;
|
||||
children: React.ReactNode;
|
||||
}) {
|
||||
return (
|
||||
<div className='space-y-1.5'>
|
||||
<p className='text-xs font-medium text-muted-foreground'>{label}</p>
|
||||
{children}
|
||||
</div>
|
||||
);
|
||||
}
|
||||
|
||||
function TimeSelect({
|
||||
value,
|
||||
options,
|
||||
onValueChange,
|
||||
}: {
|
||||
value: string;
|
||||
options: string[];
|
||||
onValueChange: (value: string) => void;
|
||||
}) {
|
||||
return (
|
||||
<Select value={value} onValueChange={onValueChange}>
|
||||
<SelectTrigger className='h-8 w-18 text-xs'>
|
||||
<SelectValue />
|
||||
</SelectTrigger>
|
||||
<SelectContent>
|
||||
{options.map((option) => (
|
||||
<SelectItem key={option} value={option}>
|
||||
{option}
|
||||
</SelectItem>
|
||||
))}
|
||||
</SelectContent>
|
||||
</Select>
|
||||
);
|
||||
}
|
||||
|
||||
/** shadcn 日期 + 时间选择器，value 为 ISO 字符串。 */
|
||||
function DateTimePicker({
|
||||
value,
|
||||
onChange,
|
||||
}: {
|
||||
value: string;
|
||||
onChange: (value: string) => void;
|
||||
}) {
|
||||
const [open, setOpen] = useState(false);
|
||||
const current = value ? new Date(value) : undefined;
|
||||
|
||||
const applyDate = (date: Date | undefined) => {
|
||||
if (!date) return;
|
||||
const next = value ? new Date(value) : new Date();
|
||||
next.setFullYear(date.getFullYear(), date.getMonth(), date.getDate());
|
||||
onChange(next.toISOString());
|
||||
};
|
||||
|
||||
const applyTime = (hh: string, mm: string) => {
|
||||
const next = value ? new Date(value) : new Date();
|
||||
next.setHours(Number(hh), Number(mm), 0, 0);
|
||||
onChange(next.toISOString());
|
||||
};
|
||||
|
||||
const hour = current ? String(current.getHours()).padStart(2, '0') : '00';
|
||||
const minute = current ? String(current.getMinutes()).padStart(2, '0') : '00';
|
||||
|
||||
return (
|
||||
<Popover open={open} onOpenChange={setOpen}>
|
||||
<PopoverTrigger asChild>
|
||||
<Button
|
||||
variant='outline'
|
||||
className='h-9 w-full justify-start gap-2 px-3 text-xs font-normal'
|
||||
>
|
||||
<CalendarIcon className='size-3.5 text-muted-foreground' />
|
||||
{current ? (
|
||||
format(current, 'yyyy-MM-dd HH:mm')
|
||||
) : (
|
||||
<span className='text-muted-foreground'>选择时间</span>
|
||||
)}
|
||||
</Button>
|
||||
</PopoverTrigger>
|
||||
<PopoverContent className='w-auto p-0' align='start'>
|
||||
<Calendar mode='single' selected={current} onSelect={applyDate} />
|
||||
<div className='flex items-center gap-1.5 border-t p-2'>
|
||||
<TimeSelect
|
||||
value={hour}
|
||||
options={HOUR_OPTIONS}
|
||||
onValueChange={(h) => applyTime(h, minute)}
|
||||
/>
|
||||
<span className='text-xs text-muted-foreground'>:</span>
|
||||
<TimeSelect
|
||||
value={minute}
|
||||
options={MINUTE_OPTIONS}
|
||||
onValueChange={(m) => applyTime(hour, m)}
|
||||
/>
|
||||
</div>
|
||||
</PopoverContent>
|
||||
</Popover>
|
||||
);
|
||||
}
|
||||
|
||||
export function AccessLogFilters({
|
||||
draft,
|
||||
pageSize,
|
||||
@@ -31,28 +153,12 @@ export function AccessLogFilters({
|
||||
onSearch,
|
||||
onReset,
|
||||
}: AccessLogFiltersProps) {
|
||||
const [moreOpen, setMoreOpen] = useState(false);
|
||||
|
||||
return (
|
||||
<div className='space-y-3'>
|
||||
<div className='grid gap-3 md:grid-cols-2 xl:grid-cols-4'>
|
||||
<div className='space-y-1.5'>
|
||||
<p className='text-xs font-medium text-muted-foreground'>节点 ID</p>
|
||||
<div className='relative'>
|
||||
<Search className='absolute left-2.5 top-2.5 size-3.5 text-muted-foreground' />
|
||||
<Input
|
||||
value={draft.nodeId}
|
||||
onChange={(e) =>
|
||||
onDraftChange({ ...draft, nodeId: e.target.value })
|
||||
}
|
||||
onKeyDown={(e) => {
|
||||
if (e.key === 'Enter') onSearch();
|
||||
}}
|
||||
placeholder='按 node_id 搜索'
|
||||
className='pl-8 h-9 text-xs'
|
||||
/>
|
||||
</div>
|
||||
</div>
|
||||
<div className='space-y-1.5'>
|
||||
<p className='text-xs font-medium text-muted-foreground'>来源 IP</p>
|
||||
<FilterField label='来源 IP'>
|
||||
<Input
|
||||
value={draft.remoteAddr}
|
||||
onChange={(e) =>
|
||||
@@ -64,9 +170,8 @@ export function AccessLogFilters({
|
||||
placeholder='按 IP 搜索'
|
||||
className='h-9 text-xs'
|
||||
/>
|
||||
</div>
|
||||
<div className='space-y-1.5'>
|
||||
<p className='text-xs font-medium text-muted-foreground'>访问域名</p>
|
||||
</FilterField>
|
||||
<FilterField label='访问域名'>
|
||||
<Input
|
||||
value={draft.host}
|
||||
onChange={(e) => onDraftChange({ ...draft, host: e.target.value })}
|
||||
@@ -76,21 +181,91 @@ export function AccessLogFilters({
|
||||
placeholder='按域名搜索'
|
||||
className='h-9 text-xs'
|
||||
/>
|
||||
</div>
|
||||
<div className='space-y-1.5'>
|
||||
<p className='text-xs font-medium text-muted-foreground'>请求路径</p>
|
||||
</FilterField>
|
||||
<FilterField label='状态码'>
|
||||
<Input
|
||||
value={draft.path}
|
||||
onChange={(e) => onDraftChange({ ...draft, path: e.target.value })}
|
||||
value={draft.statusCode}
|
||||
onChange={(e) =>
|
||||
onDraftChange({
|
||||
...draft,
|
||||
statusCode: e.target.value.replace(/\D/g, '').slice(0, 3),
|
||||
})
|
||||
}
|
||||
onKeyDown={(e) => {
|
||||
if (e.key === 'Enter') onSearch();
|
||||
}}
|
||||
placeholder='按路径搜索'
|
||||
placeholder='输入状态码，如 404'
|
||||
className='h-9 text-xs'
|
||||
/>
|
||||
</div>
|
||||
</FilterField>
|
||||
</div>
|
||||
|
||||
<Collapsible open={moreOpen} onOpenChange={setMoreOpen}>
|
||||
<CollapsibleTrigger asChild>
|
||||
<Button
|
||||
variant='ghost'
|
||||
size='sm'
|
||||
className='-ml-1 h-8 gap-1 px-1 text-xs text-muted-foreground'
|
||||
>
|
||||
更多筛选
|
||||
<ChevronDown
|
||||
className={`size-3.5 transition-transform ${
|
||||
moreOpen ? 'rotate-180' : ''
|
||||
}`}
|
||||
/>
|
||||
</Button>
|
||||
</CollapsibleTrigger>
|
||||
<CollapsibleContent>
|
||||
<div className='grid gap-3 pt-3 md:grid-cols-2 xl:grid-cols-3'>
|
||||
<FilterField label='节点 ID'>
|
||||
<div className='relative'>
|
||||
<Search className='absolute left-2.5 top-2.5 size-3.5 text-muted-foreground' />
|
||||
<Input
|
||||
value={draft.nodeId}
|
||||
onChange={(e) =>
|
||||
onDraftChange({ ...draft, nodeId: e.target.value })
|
||||
}
|
||||
onKeyDown={(e) => {
|
||||
if (e.key === 'Enter') onSearch();
|
||||
}}
|
||||
placeholder='按 node_id 搜索'
|
||||
className='pl-8 h-9 text-xs'
|
||||
/>
|
||||
</div>
|
||||
</FilterField>
|
||||
<FilterField label='请求路径'>
|
||||
<Input
|
||||
value={draft.path}
|
||||
onChange={(e) =>
|
||||
onDraftChange({ ...draft, path: e.target.value })
|
||||
}
|
||||
onKeyDown={(e) => {
|
||||
if (e.key === 'Enter') onSearch();
|
||||
}}
|
||||
placeholder='按路径搜索'
|
||||
className='h-9 text-xs'
|
||||
/>
|
||||
</FilterField>
|
||||
<FilterField label='时间范围'>
|
||||
<div className='grid grid-cols-2 gap-2'>
|
||||
<DateTimePicker
|
||||
value={draft.since}
|
||||
onChange={(value) =>
|
||||
onDraftChange({ ...draft, since: value })
|
||||
}
|
||||
/>
|
||||
<DateTimePicker
|
||||
value={draft.until}
|
||||
onChange={(value) =>
|
||||
onDraftChange({ ...draft, until: value })
|
||||
}
|
||||
/>
|
||||
</div>
|
||||
</FilterField>
|
||||
</div>
|
||||
</CollapsibleContent>
|
||||
</Collapsible>
|
||||
|
||||
<div className='flex flex-col gap-3 sm:flex-row sm:items-end sm:justify-between'>
|
||||
<div className='space-y-1.5 w-full sm:max-w-[180px]'>
|
||||
<p className='text-xs font-medium text-muted-foreground'>每页条数</p>
|
||||
|
||||
@@ -5,6 +5,9 @@ export type SearchDraft = {
|
||||
remoteAddr: string;
|
||||
host: string;
|
||||
path: string;
|
||||
statusCode: string;
|
||||
since: string;
|
||||
until: string;
|
||||
};
|
||||
|
||||
export type OverviewRangeHours = 24 | 168 | 360 | 720;
|
||||
|
||||
@@ -244,8 +244,12 @@ function PieDistributionCard({
|
||||
}
|
||||
/>
|
||||
<ChartLegend
|
||||
content={<ChartLegendContent nameKey='name' />}
|
||||
className='flex-wrap justify-center gap-x-4 gap-y-1 pt-2 text-[11px]'
|
||||
content={
|
||||
<ChartLegendContent
|
||||
nameKey='name'
|
||||
className='flex-wrap justify-center gap-x-4 gap-y-1 pt-2 text-[11px]'
|
||||
/>
|
||||
}
|
||||
/>
|
||||
</PieChart>
|
||||
</ChartContainer>
|
||||
|
||||
@@ -33,6 +33,9 @@ const emptyDraft: SearchDraft = {
|
||||
remoteAddr: '',
|
||||
host: '',
|
||||
path: '',
|
||||
statusCode: '',
|
||||
since: '',
|
||||
until: '',
|
||||
};
|
||||
|
||||
function resolveTab(value: string | null): AccessLogTab {
|
||||
@@ -111,6 +114,11 @@ function AccessLogsPageContent() {
|
||||
remote_addr: filters.remoteAddr || undefined,
|
||||
host: filters.host || undefined,
|
||||
path: filters.path || undefined,
|
||||
status_code: filters.statusCode
|
||||
? Number.parseInt(filters.statusCode, 10)
|
||||
: undefined,
|
||||
since: filters.since || undefined,
|
||||
until: filters.until || undefined,
|
||||
p: page,
|
||||
page_size: pageSize,
|
||||
sort_by: detailSortState.sortBy,
|
||||
@@ -161,6 +169,9 @@ function AccessLogsPageContent() {
|
||||
remoteAddr: draft.remoteAddr.trim(),
|
||||
host: draft.host.trim(),
|
||||
path: draft.path.trim(),
|
||||
statusCode: draft.statusCode.trim(),
|
||||
since: draft.since.trim(),
|
||||
until: draft.until.trim(),
|
||||
});
|
||||
setPage(0);
|
||||
}, [draft]);
|
||||
|
||||
@@ -484,8 +484,12 @@ export function FileStats() {
|
||||
}
|
||||
/>
|
||||
<ChartLegend
|
||||
content={<ChartLegendContent nameKey='name' />}
|
||||
className='flex-wrap justify-center gap-x-4 gap-y-1 text-[11px] pt-4'
|
||||
content={
|
||||
<ChartLegendContent
|
||||
nameKey='name'
|
||||
className='flex-wrap justify-center gap-x-4 gap-y-1 text-[11px] pt-4'
|
||||
/>
|
||||
}
|
||||
/>
|
||||
</PieChart>
|
||||
</ChartContainer>
|
||||
@@ -577,8 +581,12 @@ export function FileStats() {
|
||||
}
|
||||
/>
|
||||
<ChartLegend
|
||||
content={<ChartLegendContent nameKey='name' />}
|
||||
className='flex-wrap justify-center gap-x-4 gap-y-1 text-[11px] pt-4'
|
||||
content={
|
||||
<ChartLegendContent
|
||||
nameKey='name'
|
||||
className='flex-wrap justify-center gap-x-4 gap-y-1 text-[11px] pt-4'
|
||||
/>
|
||||
}
|
||||
/>
|
||||
</PieChart>
|
||||
</ChartContainer>
|
||||
|
||||
@@ -18,8 +18,6 @@ export type OpenFlareOpsFields = {
|
||||
uptime_kuma_retry: string;
|
||||
uptime_kuma_retry_interval: string;
|
||||
uptime_kuma_timeout: string;
|
||||
database_auto_cleanup_enabled: boolean;
|
||||
database_auto_cleanup_retention_days: string;
|
||||
pages_max_package_size_mb: string;
|
||||
pages_max_history_count: string;
|
||||
};
|
||||
@@ -42,8 +40,6 @@ export const defaultOpenFlareOpsFields: OpenFlareOpsFields = {
|
||||
uptime_kuma_retry: '0',
|
||||
uptime_kuma_retry_interval: '60',
|
||||
uptime_kuma_timeout: '48',
|
||||
database_auto_cleanup_enabled: false,
|
||||
database_auto_cleanup_retention_days: '30',
|
||||
pages_max_package_size_mb: '100',
|
||||
pages_max_history_count: '20',
|
||||
};
|
||||
@@ -88,12 +84,6 @@ export function mapOptionsToOpsFields(
|
||||
uptime_kuma_retry: optionMap.uptime_kuma_retry ?? '0',
|
||||
uptime_kuma_retry_interval: optionMap.uptime_kuma_retry_interval ?? '60',
|
||||
uptime_kuma_timeout: optionMap.uptime_kuma_timeout ?? '48',
|
||||
database_auto_cleanup_enabled: toBoolean(
|
||||
optionMap.database_auto_cleanup_enabled,
|
||||
false,
|
||||
),
|
||||
database_auto_cleanup_retention_days:
|
||||
optionMap.database_auto_cleanup_retention_days ?? '30',
|
||||
pages_max_package_size_mb: optionMap.pages_max_package_size_mb ?? '100',
|
||||
pages_max_history_count: optionMap.pages_max_history_count ?? '20',
|
||||
};
|
||||
@@ -165,16 +155,6 @@ export function validateUptimeKumaFields(fields: OpenFlareOpsFields) {
|
||||
throw new Error('请求超时必须为正整数。');
|
||||
}
|
||||
|
||||
export function validateDatabaseAutoCleanup(fields: OpenFlareOpsFields) {
|
||||
const retentionDays = Number.parseInt(
|
||||
fields.database_auto_cleanup_retention_days,
|
||||
10,
|
||||
);
|
||||
if (Number.isNaN(retentionDays) || retentionDays < 1) {
|
||||
throw new Error('自动清理保留天数至少为 1 天。');
|
||||
}
|
||||
}
|
||||
|
||||
export function agentOptionEntries(fields: OpenFlareOpsFields): OptionItem[] {
|
||||
validateAgentFields(fields);
|
||||
return [
|
||||
@@ -220,22 +200,6 @@ export function uptimeKumaOptionEntries(
|
||||
];
|
||||
}
|
||||
|
||||
export function databaseAutoCleanupEntries(
|
||||
fields: OpenFlareOpsFields,
|
||||
): OptionItem[] {
|
||||
validateDatabaseAutoCleanup(fields);
|
||||
return [
|
||||
{
|
||||
key: 'database_auto_cleanup_enabled',
|
||||
value: String(fields.database_auto_cleanup_enabled),
|
||||
},
|
||||
{
|
||||
key: 'database_auto_cleanup_retention_days',
|
||||
value: fields.database_auto_cleanup_retention_days,
|
||||
},
|
||||
];
|
||||
}
|
||||
|
||||
export function validatePagesFields(fields: OpenFlareOpsFields) {
|
||||
const packageSize = Number.parseInt(fields.pages_max_package_size_mb, 10);
|
||||
const historyCount = Number.parseInt(fields.pages_max_history_count, 10);
|
||||
|
||||
@@ -11,20 +11,8 @@ import {
|
||||
RotateCw,
|
||||
Save,
|
||||
Server,
|
||||
Trash2,
|
||||
} from 'lucide-react';
|
||||
import { toast } from 'sonner';
|
||||
|
||||
import {
|
||||
AlertDialog,
|
||||
AlertDialogAction,
|
||||
AlertDialogCancel,
|
||||
AlertDialogContent,
|
||||
AlertDialogDescription,
|
||||
AlertDialogFooter,
|
||||
AlertDialogHeader,
|
||||
AlertDialogTitle,
|
||||
} from '@/components/ui/alert-dialog';
|
||||
import { Button } from '@/components/ui/button';
|
||||
import {
|
||||
Card,
|
||||
@@ -46,7 +34,6 @@ import { Switch } from '@/components/ui/switch';
|
||||
import { Textarea } from '@/components/ui/textarea';
|
||||
import { ErrorInline } from '@/components/layout/error';
|
||||
import { LoadingStateWithBorder } from '@/components/layout/loading';
|
||||
import type { DatabaseCleanupTarget } from '@/lib/services/openflare';
|
||||
import {
|
||||
NodeService,
|
||||
OptionService,
|
||||
@@ -57,7 +44,6 @@ import {
|
||||
import {
|
||||
agentOptionEntries,
|
||||
buildDiscoveryCommand,
|
||||
databaseAutoCleanupEntries,
|
||||
defaultOpenFlareOpsFields,
|
||||
formatDurationLabel,
|
||||
getBrowserOrigin,
|
||||
@@ -72,31 +58,6 @@ import { UptimeKumaSiteSelectModal } from './uptimekuma-site-modal';
|
||||
const optionsQueryKey = ['openflare', 'options'] as const;
|
||||
const openflarePublicStatusQueryKey = ['openflare', 'public-status'] as const;
|
||||
|
||||
const cleanupTargets: Array<{
|
||||
target: DatabaseCleanupTarget;
|
||||
label: string;
|
||||
description: string;
|
||||
}> = [
|
||||
{
|
||||
target: 'node_access_logs',
|
||||
label: '访问日志',
|
||||
description:
|
||||
'清理 node_access_logs，影响访问明细与 IP 汇总；表 TTL 为 90 天。',
|
||||
},
|
||||
{
|
||||
target: 'node_metric_snapshots',
|
||||
label: '性能快照',
|
||||
description:
|
||||
'清理 node_metric_snapshots，影响节点资源趋势；表 TTL 为 30 天。',
|
||||
},
|
||||
{
|
||||
target: 'node_edge_health',
|
||||
label: 'OpenResty 健康',
|
||||
description:
|
||||
'清理 node_edge_health（OpenResty 连接/健康快照）；表 TTL 为 30 天。业务流量请清理访问日志。',
|
||||
},
|
||||
];
|
||||
|
||||
async function copyText(value: string) {
|
||||
await navigator.clipboard.writeText(value);
|
||||
}
|
||||
@@ -109,11 +70,6 @@ export function OpenFlareOpsSettings() {
|
||||
const [savingSection, setSavingSection] = useState<string | null>(null);
|
||||
const [geoIPTestIP, setGeoIPTestIP] = useState('8.8.8.8');
|
||||
const [uptimeKumaModalOpen, setUptimeKumaModalOpen] = useState(false);
|
||||
const [cleanupTarget, setCleanupTarget] = useState<{
|
||||
target: DatabaseCleanupTarget;
|
||||
label: string;
|
||||
} | null>(null);
|
||||
const [cleanupRetentionDays, setCleanupRetentionDays] = useState('');
|
||||
|
||||
const optionsQuery = useQuery({
|
||||
queryKey: optionsQueryKey,
|
||||
@@ -194,25 +150,6 @@ export function OpenFlareOpsSettings() {
|
||||
toast.error(error instanceof Error ? error.message : '同步失败'),
|
||||
});
|
||||
|
||||
const cleanupMutation = useMutation({
|
||||
mutationFn: (payload: {
|
||||
target: DatabaseCleanupTarget;
|
||||
retention_days?: number;
|
||||
}) => OptionService.cleanupDatabase(payload),
|
||||
onSuccess: (result) => {
|
||||
setCleanupTarget(null);
|
||||
setCleanupRetentionDays('');
|
||||
toast.success(
|
||||
result.delete_all
|
||||
? `已清空${result.target_label}，共删除 ${result.deleted_count} 条。`
|
||||
: `已清理${result.target_label}，共删除 ${result.deleted_count} 条。`,
|
||||
);
|
||||
},
|
||||
onError: (error) => {
|
||||
toast.error(error instanceof Error ? error.message : '清理失败');
|
||||
},
|
||||
});
|
||||
|
||||
const discoveryToken = bootstrapQuery.data?.discovery_token ?? '';
|
||||
const discoveryCommand = useMemo(() => {
|
||||
if (!fields.server_address || !discoveryToken) return '';
|
||||
@@ -248,17 +185,6 @@ export function OpenFlareOpsSettings() {
|
||||
}
|
||||
};
|
||||
|
||||
const saveDatabaseAutoCleanup = () => {
|
||||
try {
|
||||
saveMutation.mutate({
|
||||
section: 'database-auto',
|
||||
entries: databaseAutoCleanupEntries(fields),
|
||||
});
|
||||
} catch (error) {
|
||||
toast.error(error instanceof Error ? error.message : '参数校验失败');
|
||||
}
|
||||
};
|
||||
|
||||
const savePagesSettings = () => {
|
||||
try {
|
||||
saveMutation.mutate({
|
||||
@@ -690,86 +616,6 @@ export function OpenFlareOpsSettings() {
|
||||
</CardContent>
|
||||
</Card>
|
||||
|
||||
<div className='grid gap-6 xl:grid-cols-2'>
|
||||
<Card className='border-dashed shadow-none'>
|
||||
<CardHeader className='flex flex-row items-center justify-between gap-4'>
|
||||
<div>
|
||||
<CardTitle className='text-base'>数据库自动清理</CardTitle>
|
||||
<CardDescription>
|
||||
每天凌晨 3 点物化 ClickHouse 表 TTL；访问日志至少保留 90
|
||||
天，其它观测数据至少保留 30 天。
|
||||
</CardDescription>
|
||||
</div>
|
||||
<Button
|
||||
size='sm'
|
||||
disabled={savingSection === 'database-auto'}
|
||||
onClick={saveDatabaseAutoCleanup}
|
||||
>
|
||||
保存
|
||||
</Button>
|
||||
</CardHeader>
|
||||
<CardContent className='space-y-4'>
|
||||
<ToggleRow
|
||||
label='启用每日自动清理'
|
||||
checked={fields.database_auto_cleanup_enabled}
|
||||
onChange={(value) =>
|
||||
updateField('database_auto_cleanup_enabled', value)
|
||||
}
|
||||
/>
|
||||
<div className='space-y-1.5'>
|
||||
<FieldInput
|
||||
label='期望保留天数'
|
||||
value={fields.database_auto_cleanup_retention_days}
|
||||
type='number'
|
||||
onChange={(value) =>
|
||||
updateField('database_auto_cleanup_retention_days', value)
|
||||
}
|
||||
/>
|
||||
<p className='text-xs text-muted-foreground'>
|
||||
小于表 TTL 时自动按下限执行：访问日志 90 天，其它观测数据 30
|
||||
天。
|
||||
</p>
|
||||
</div>
|
||||
</CardContent>
|
||||
</Card>
|
||||
|
||||
<Card className='border-dashed shadow-none'>
|
||||
<CardHeader>
|
||||
<CardTitle className='text-base'>手动数据清理</CardTitle>
|
||||
<CardDescription>
|
||||
按表 TTL 清理；输入天数不能小于对应表
|
||||
TTL，留空时将删除该类数据的全部历史记录。
|
||||
</CardDescription>
|
||||
</CardHeader>
|
||||
<CardContent className='space-y-3'>
|
||||
{cleanupTargets.map((item) => (
|
||||
<div
|
||||
key={item.target}
|
||||
className='flex items-start justify-between gap-3 rounded-lg border border-dashed p-3'
|
||||
>
|
||||
<div>
|
||||
<p className='text-sm font-medium'>{item.label}</p>
|
||||
<p className='mt-1 text-xs text-muted-foreground'>
|
||||
{item.description}
|
||||
</p>
|
||||
</div>
|
||||
<Button
|
||||
type='button'
|
||||
variant='destructive'
|
||||
size='sm'
|
||||
onClick={() =>
|
||||
setCleanupTarget({ target: item.target, label: item.label })
|
||||
}
|
||||
>
|
||||
<Trash2 className='size-3.5 mr-1' />
|
||||
清理
|
||||
</Button>
|
||||
</div>
|
||||
))}
|
||||
</CardContent>
|
||||
</Card>
|
||||
</div>
|
||||
|
||||
<UptimeKumaSiteSelectModal
|
||||
open={uptimeKumaModalOpen}
|
||||
selectedSites={
|
||||
@@ -782,56 +628,6 @@ export function OpenFlareOpsSettings() {
|
||||
updateField('uptime_kuma_selected_sites', sites.join(','))
|
||||
}
|
||||
/>
|
||||
|
||||
<AlertDialog
|
||||
open={cleanupTarget !== null}
|
||||
onOpenChange={(open) => !open && setCleanupTarget(null)}
|
||||
>
|
||||
<AlertDialogContent>
|
||||
<AlertDialogHeader>
|
||||
<AlertDialogTitle>清理{cleanupTarget?.label}</AlertDialogTitle>
|
||||
<AlertDialogDescription>
|
||||
输入保留天数后会按该表 TTL 物化过期数据；小于表 TTL
|
||||
的天数会被拒绝。留空则删除全部历史记录，操作不可恢复。
|
||||
</AlertDialogDescription>
|
||||
</AlertDialogHeader>
|
||||
<FieldInput
|
||||
label='保留天数'
|
||||
value={cleanupRetentionDays}
|
||||
type='number'
|
||||
onChange={setCleanupRetentionDays}
|
||||
placeholder='留空则全部删除'
|
||||
/>
|
||||
<AlertDialogFooter>
|
||||
<AlertDialogCancel disabled={cleanupMutation.isPending}>
|
||||
取消
|
||||
</AlertDialogCancel>
|
||||
<AlertDialogAction
|
||||
disabled={cleanupMutation.isPending}
|
||||
onClick={(event) => {
|
||||
event.preventDefault();
|
||||
if (!cleanupTarget) return;
|
||||
const trimmed = cleanupRetentionDays.trim();
|
||||
if (trimmed !== '') {
|
||||
const retentionDays = Number.parseInt(trimmed, 10);
|
||||
if (Number.isNaN(retentionDays) || retentionDays < 1) {
|
||||
toast.error('保留天数至少为 1 天');
|
||||
return;
|
||||
}
|
||||
cleanupMutation.mutate({
|
||||
target: cleanupTarget.target,
|
||||
retention_days: retentionDays,
|
||||
});
|
||||
return;
|
||||
}
|
||||
cleanupMutation.mutate({ target: cleanupTarget.target });
|
||||
}}
|
||||
>
|
||||
{cleanupMutation.isPending ? '清理中...' : '确认清理'}
|
||||
</AlertDialogAction>
|
||||
</AlertDialogFooter>
|
||||
</AlertDialogContent>
|
||||
</AlertDialog>
|
||||
</div>
|
||||
);
|
||||
}
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
'use client';
|
||||
|
||||
import { useCallback, useEffect, useState } from 'react';
|
||||
import { useCallback, useEffect, useMemo, useState } from 'react';
|
||||
import { toast } from 'sonner';
|
||||
import { Button } from '@/components/ui/button';
|
||||
import { Input } from '@/components/ui/input';
|
||||
@@ -8,6 +8,13 @@ import { Label } from '@/components/ui/label';
|
||||
import { Textarea } from '@/components/ui/textarea';
|
||||
import { Switch } from '@/components/ui/switch';
|
||||
import { Spinner } from '@/components/ui/spinner';
|
||||
import {
|
||||
Select,
|
||||
SelectContent,
|
||||
SelectItem,
|
||||
SelectTrigger,
|
||||
SelectValue,
|
||||
} from '@/components/ui/select';
|
||||
import {
|
||||
Dialog,
|
||||
DialogContent,
|
||||
@@ -19,12 +26,17 @@ import {
|
||||
import {
|
||||
Calendar as CalendarIcon,
|
||||
Clock,
|
||||
Database,
|
||||
Info,
|
||||
Layers,
|
||||
Play,
|
||||
} from 'lucide-react';
|
||||
|
||||
import type { DispatchTaskRequest, TaskMeta } from '@/lib/services/admin';
|
||||
import type {
|
||||
DispatchTaskRequest,
|
||||
LogDatabaseStatus,
|
||||
TaskMeta,
|
||||
} from '@/lib/services/admin';
|
||||
import services from '@/lib/services';
|
||||
import { buildTaskPayload } from '@/lib/task-param-utils';
|
||||
import { ErrorInline } from '@/components/layout/error';
|
||||
@@ -68,6 +80,18 @@ const TASK_CONFIGS: Record<
|
||||
gradient:
|
||||
'from-rose-500/10 via-rose-500/5 to-transparent border-rose-200/50 dark:border-rose-800/50 hover:border-rose-400 dark:hover:border-rose-500',
|
||||
},
|
||||
of_log_db_switch: {
|
||||
icon: Database,
|
||||
color: 'text-teal-600 dark:text-teal-400',
|
||||
gradient:
|
||||
'from-teal-500/10 via-teal-500/5 to-transparent border-teal-200/50 dark:border-teal-800/50 hover:border-teal-400 dark:hover:border-teal-500',
|
||||
},
|
||||
};
|
||||
|
||||
const LOG_DATABASE_LABELS: Record<string, string> = {
|
||||
postgres: 'PostgreSQL（主库）',
|
||||
sqlite: 'SQLite（主库）',
|
||||
clickhouse: 'ClickHouse',
|
||||
};
|
||||
|
||||
const DEFAULT_TASK_CONFIG = {
|
||||
@@ -192,9 +216,38 @@ export function TaskManager() {
|
||||
}
|
||||
}, []);
|
||||
|
||||
const [logDbStatus, setLogDbStatus] = useState<LogDatabaseStatus | null>(
|
||||
null,
|
||||
);
|
||||
|
||||
// 日志库状态用于「切换日志数据库」卡片与 target 下拉；获取失败不阻塞任务列表。
|
||||
const fetchLogDbStatus = useCallback(async () => {
|
||||
try {
|
||||
const data = await services.adminStatus.getLogDatabaseStatus();
|
||||
setLogDbStatus(data);
|
||||
} catch {
|
||||
setLogDbStatus(null);
|
||||
}
|
||||
}, []);
|
||||
|
||||
useEffect(() => {
|
||||
fetchTaskTypes();
|
||||
}, [fetchTaskTypes]);
|
||||
fetchLogDbStatus();
|
||||
}, [fetchTaskTypes, fetchLogDbStatus]);
|
||||
|
||||
const availableLogDbTargets = useMemo(
|
||||
() => logDbStatus?.available_targets ?? [],
|
||||
[logDbStatus],
|
||||
);
|
||||
|
||||
const retentionSummary = useMemo(() => {
|
||||
const days = logDbStatus?.retention_days ?? {};
|
||||
const parts: string[] = [];
|
||||
if (days.postgres != null) parts.push(`PG ${days.postgres}`);
|
||||
if (days.sqlite != null) parts.push(`SQLite ${days.sqlite}`);
|
||||
if (days.clickhouse != null) parts.push(`CH ${days.clickhouse}`);
|
||||
return parts.join(' / ');
|
||||
}, [logDbStatus]);
|
||||
|
||||
useEffect(() => {
|
||||
if (selectedTaskType) {
|
||||
@@ -344,6 +397,45 @@ export function TaskManager() {
|
||||
</div>
|
||||
</div>
|
||||
|
||||
{task.type === 'of_log_db_switch' && logDbStatus && (
|
||||
<div className='pt-3 mt-3 border-t border-border/50 space-y-1.5'>
|
||||
<div className='flex items-center justify-between gap-2'>
|
||||
<span className='text-[10px] text-muted-foreground shrink-0'>
|
||||
日志主库
|
||||
</span>
|
||||
<span className='text-[10px] font-mono text-foreground truncate'>
|
||||
{LOG_DATABASE_LABELS[logDbStatus.active_database] ||
|
||||
logDbStatus.active_database}
|
||||
</span>
|
||||
</div>
|
||||
<div className='flex items-center justify-between gap-2'>
|
||||
<span className='text-[10px] text-muted-foreground shrink-0'>
|
||||
保留天数
|
||||
</span>
|
||||
<span className='text-[10px] font-mono text-muted-foreground truncate'>
|
||||
{retentionSummary || '-'}
|
||||
</span>
|
||||
</div>
|
||||
<div className='flex items-center justify-between gap-2'>
|
||||
<span className='text-[10px] text-muted-foreground shrink-0'>
|
||||
迁移状态
|
||||
</span>
|
||||
<Badge
|
||||
variant={
|
||||
logDbStatus.migration === 'migrating'
|
||||
? 'default'
|
||||
: 'outline'
|
||||
}
|
||||
className='text-[10px] h-5 px-1.5'
|
||||
>
|
||||
{logDbStatus.migration === 'migrating'
|
||||
? '迁移中'
|
||||
: '空闲'}
|
||||
</Badge>
|
||||
</div>
|
||||
</div>
|
||||
)}
|
||||
|
||||
<div className='pt-4 mt-1'>
|
||||
<Button
|
||||
className='w-full h-7 text-xs'
|
||||
@@ -436,70 +528,104 @@ export function TaskManager() {
|
||||
}
|
||||
return (
|
||||
<div className='space-y-4'>
|
||||
{targetTask.params.map((param) => (
|
||||
<div key={param.name} className='grid gap-2'>
|
||||
<Label
|
||||
htmlFor={`param-${param.name}`}
|
||||
className='flex items-center gap-1'
|
||||
>
|
||||
{param.label}
|
||||
{param.required && (
|
||||
<span className='text-destructive font-bold'>*</span>
|
||||
)}
|
||||
</Label>
|
||||
{param.type === 'text' ? (
|
||||
<Textarea
|
||||
id={`param-${param.name}`}
|
||||
placeholder={param.placeholder}
|
||||
className='text-xs min-h-[80px]'
|
||||
value={paramValues[param.name] || ''}
|
||||
onChange={(e) =>
|
||||
setParamValues((prev) => ({
|
||||
...prev,
|
||||
[param.name]: e.target.value,
|
||||
}))
|
||||
}
|
||||
/>
|
||||
) : param.type === 'boolean' ? (
|
||||
<div className='flex items-center gap-2 pt-1 h-9'>
|
||||
<Switch
|
||||
{targetTask.params.map((param) => {
|
||||
const isSwitchTarget =
|
||||
param.name === 'target' &&
|
||||
getSelectedTaskMeta()?.type === 'of_log_db_switch';
|
||||
return (
|
||||
<div key={param.name} className='grid gap-2'>
|
||||
<Label
|
||||
htmlFor={`param-${param.name}`}
|
||||
className='flex items-center gap-1'
|
||||
>
|
||||
{param.label}
|
||||
{param.required && (
|
||||
<span className='text-destructive font-bold'>
|
||||
*
|
||||
</span>
|
||||
)}
|
||||
</Label>
|
||||
{param.type === 'text' ? (
|
||||
<Textarea
|
||||
id={`param-${param.name}`}
|
||||
checked={paramValues[param.name] === 'true'}
|
||||
onCheckedChange={(checked) =>
|
||||
placeholder={param.placeholder}
|
||||
className='text-xs min-h-[80px]'
|
||||
value={paramValues[param.name] || ''}
|
||||
onChange={(e) =>
|
||||
setParamValues((prev) => ({
|
||||
...prev,
|
||||
[param.name]: checked ? 'true' : 'false',
|
||||
[param.name]: e.target.value,
|
||||
}))
|
||||
}
|
||||
/>
|
||||
<span className='text-xs text-muted-foreground'>
|
||||
{paramValues[param.name] === 'true'
|
||||
? '开启'
|
||||
: '关闭'}
|
||||
</span>
|
||||
</div>
|
||||
) : (
|
||||
<Input
|
||||
id={`param-${param.name}`}
|
||||
type={param.type === 'number' ? 'number' : 'text'}
|
||||
placeholder={param.placeholder}
|
||||
className='text-xs'
|
||||
value={paramValues[param.name] || ''}
|
||||
onChange={(e) =>
|
||||
setParamValues((prev) => ({
|
||||
...prev,
|
||||
[param.name]: e.target.value,
|
||||
}))
|
||||
}
|
||||
/>
|
||||
)}
|
||||
{param.description && (
|
||||
<p className='text-[10px] text-muted-foreground'>
|
||||
{param.description}
|
||||
</p>
|
||||
)}
|
||||
</div>
|
||||
))}
|
||||
) : param.type === 'boolean' ? (
|
||||
<div className='flex items-center gap-2 pt-1 h-9'>
|
||||
<Switch
|
||||
id={`param-${param.name}`}
|
||||
checked={paramValues[param.name] === 'true'}
|
||||
onCheckedChange={(checked) =>
|
||||
setParamValues((prev) => ({
|
||||
...prev,
|
||||
[param.name]: checked ? 'true' : 'false',
|
||||
}))
|
||||
}
|
||||
/>
|
||||
<span className='text-xs text-muted-foreground'>
|
||||
{paramValues[param.name] === 'true'
|
||||
? '开启'
|
||||
: '关闭'}
|
||||
</span>
|
||||
</div>
|
||||
) : isSwitchTarget &&
|
||||
availableLogDbTargets.length > 0 ? (
|
||||
<Select
|
||||
value={paramValues[param.name] || ''}
|
||||
onValueChange={(value) =>
|
||||
setParamValues((prev) => ({
|
||||
...prev,
|
||||
[param.name]: value,
|
||||
}))
|
||||
}
|
||||
disabled={dispatching}
|
||||
>
|
||||
<SelectTrigger
|
||||
id={`param-${param.name}`}
|
||||
className='w-full text-xs'
|
||||
size='sm'
|
||||
>
|
||||
<SelectValue placeholder='选择目标日志库...' />
|
||||
</SelectTrigger>
|
||||
<SelectContent>
|
||||
{availableLogDbTargets.map((target) => (
|
||||
<SelectItem key={target} value={target}>
|
||||
{LOG_DATABASE_LABELS[target] || target}
|
||||
</SelectItem>
|
||||
))}
|
||||
</SelectContent>
|
||||
</Select>
|
||||
) : (
|
||||
<Input
|
||||
id={`param-${param.name}`}
|
||||
type={param.type === 'number' ? 'number' : 'text'}
|
||||
placeholder={param.placeholder}
|
||||
className='text-xs'
|
||||
value={paramValues[param.name] || ''}
|
||||
onChange={(e) =>
|
||||
setParamValues((prev) => ({
|
||||
...prev,
|
||||
[param.name]: e.target.value,
|
||||
}))
|
||||
}
|
||||
/>
|
||||
)}
|
||||
{param.description && (
|
||||
<p className='text-[10px] text-muted-foreground'>
|
||||
{param.description}
|
||||
</p>
|
||||
)}
|
||||
</div>
|
||||
);
|
||||
})}
|
||||
</div>
|
||||
);
|
||||
})()}
|
||||
|
||||
@@ -1,60 +0,0 @@
|
||||
'use client';
|
||||
|
||||
import { Globe2 } from 'lucide-react';
|
||||
|
||||
import {
|
||||
Card,
|
||||
CardContent,
|
||||
CardDescription,
|
||||
CardHeader,
|
||||
CardTitle,
|
||||
} from '@/components/ui/card';
|
||||
import { Progress } from '@/components/ui/progress';
|
||||
import type { DistributionItem } from '@/lib/services/openflare';
|
||||
|
||||
import { formatCompactNumber } from './dashboard-utils';
|
||||
|
||||
export function GeoDistributionList({ items }: { items: DistributionItem[] }) {
|
||||
const sortedItems = [...items]
|
||||
.sort((left, right) => right.value - left.value)
|
||||
.slice(0, 8);
|
||||
const maxValue = sortedItems[0]?.value ?? 0;
|
||||
|
||||
return (
|
||||
<Card className='border-dashed shadow-none'>
|
||||
<CardHeader>
|
||||
<CardTitle className='text-sm font-semibold flex items-center gap-1.5'>
|
||||
<Globe2 className='size-4 text-primary' />
|
||||
来源国家分布
|
||||
</CardTitle>
|
||||
<CardDescription className='text-xs'>
|
||||
聚合最近 24 小时主要来源国家。
|
||||
</CardDescription>
|
||||
</CardHeader>
|
||||
<CardContent>
|
||||
{sortedItems.length === 0 ? (
|
||||
<div className='flex min-h-[180px] items-center justify-center text-xs text-muted-foreground'>
|
||||
暂无来源分布数据
|
||||
</div>
|
||||
) : (
|
||||
<div className='space-y-3'>
|
||||
{sortedItems.map((item) => {
|
||||
const ratio = maxValue > 0 ? (item.value / maxValue) * 100 : 0;
|
||||
return (
|
||||
<div key={item.key} className='space-y-1.5'>
|
||||
<div className='flex items-center justify-between text-xs'>
|
||||
<span className='font-medium'>{item.key || '未知'}</span>
|
||||
<span className='font-mono tabular-nums text-muted-foreground'>
|
||||
{formatCompactNumber(item.value)}
|
||||
</span>
|
||||
</div>
|
||||
<Progress value={ratio} className='h-1.5' />
|
||||
</div>
|
||||
);
|
||||
})}
|
||||
</div>
|
||||
)}
|
||||
</CardContent>
|
||||
</Card>
|
||||
);
|
||||
}
|
||||
+21
-35
@@ -3,39 +3,25 @@
|
||||
import { TrendChart } from '@/components/data/trend-chart';
|
||||
import { Card, CardContent, CardHeader, CardTitle } from '@/components/ui/card';
|
||||
import type {
|
||||
DiskIOTrendPoint,
|
||||
CapacityTrendPoint,
|
||||
NetworkTrendPoint,
|
||||
} from '@/lib/services/openflare';
|
||||
|
||||
import {
|
||||
formatBytes,
|
||||
formatBytesPerSecond,
|
||||
formatTrendHour,
|
||||
} from './dashboard-utils';
|
||||
import { formatBytes, formatPercent, formatTrendHour } from './dashboard-utils';
|
||||
|
||||
/** Backend disk points are per-hour totals; chart displays bytes/s within each hour. */
|
||||
const DISK_BUCKET_SECONDS = 3600;
|
||||
|
||||
function diskBytesToRate(bytes: number) {
|
||||
return bytes > 0 ? bytes / DISK_BUCKET_SECONDS : 0;
|
||||
}
|
||||
|
||||
function formatDiskRate(bytesPerSecond: number) {
|
||||
return formatBytesPerSecond(bytesPerSecond, 1, { zeroText: '0 B' });
|
||||
}
|
||||
|
||||
export function NetworkDiskTrendChart({
|
||||
/** 业务流量（来自访问日志）与容量趋势（节点 Agent 宿主机指标）合并展示。 */
|
||||
export function TrafficCapacityTrendChart({
|
||||
networkPoints,
|
||||
diskPoints,
|
||||
capacityPoints,
|
||||
}: {
|
||||
networkPoints: NetworkTrendPoint[];
|
||||
diskPoints: DiskIOTrendPoint[];
|
||||
capacityPoints: CapacityTrendPoint[];
|
||||
}) {
|
||||
return (
|
||||
<Card className='border-dashed shadow-none'>
|
||||
<CardHeader>
|
||||
<CardTitle className='text-sm font-semibold'>
|
||||
24 小时业务流量与宿主机磁盘
|
||||
24 小时业务流量与容量趋势
|
||||
</CardTitle>
|
||||
</CardHeader>
|
||||
<CardContent className='space-y-6'>
|
||||
@@ -66,31 +52,31 @@ export function NetworkDiskTrendChart({
|
||||
/>
|
||||
|
||||
<TrendChart
|
||||
labels={diskPoints.map((point) =>
|
||||
labels={capacityPoints.map((point) =>
|
||||
formatTrendHour(point.bucket_started_at),
|
||||
)}
|
||||
height={180}
|
||||
summaryScope='average'
|
||||
summaryHint='近 24 小时 · 宿主机磁盘 · 平均速率'
|
||||
yAxisValueFormatter={formatDiskRate}
|
||||
summaryHint='近 24 小时 · 宿主机容量 · 平均值'
|
||||
yAxisValueFormatter={formatPercent}
|
||||
series={[
|
||||
{
|
||||
label: '磁盘读',
|
||||
color: '#a78bfa',
|
||||
fillColor: 'rgba(167, 139, 250, 0.14)',
|
||||
label: '平均 CPU',
|
||||
color: '#0f766e',
|
||||
fillColor: 'rgba(15, 118, 110, 0.15)',
|
||||
variant: 'area',
|
||||
values: diskPoints.map((point) =>
|
||||
diskBytesToRate(point.disk_read_bytes),
|
||||
values: capacityPoints.map(
|
||||
(point) => point.average_cpu_usage_percent,
|
||||
),
|
||||
valueFormatter: formatDiskRate,
|
||||
valueFormatter: formatPercent,
|
||||
},
|
||||
{
|
||||
label: '磁盘写',
|
||||
color: '#fb7185',
|
||||
values: diskPoints.map((point) =>
|
||||
diskBytesToRate(point.disk_write_bytes),
|
||||
label: '平均内存',
|
||||
color: '#2563eb',
|
||||
values: capacityPoints.map(
|
||||
(point) => point.average_memory_usage_percent,
|
||||
),
|
||||
valueFormatter: formatDiskRate,
|
||||
valueFormatter: formatPercent,
|
||||
},
|
||||
]}
|
||||
/>
|
||||
@@ -15,7 +15,7 @@ import { formatTrendHour } from './dashboard-utils';
|
||||
export function TrafficTrendChart({
|
||||
points,
|
||||
title = '24 小时请求趋势',
|
||||
description = '观察整体请求量和错误量是否出现异常抬升。',
|
||||
description = '按小时拆分请求总量与 2xx/4xx/5xx 状态码请求量，判断各状态是否异常抬升。',
|
||||
}: {
|
||||
points: TrafficTrendPoint[];
|
||||
title?: string;
|
||||
@@ -43,9 +43,19 @@ export function TrafficTrendChart({
|
||||
values: points.map((point) => point.request_count),
|
||||
},
|
||||
{
|
||||
label: '错误量',
|
||||
label: '2xx 请求',
|
||||
color: '#22c55e',
|
||||
values: points.map((point) => point.status_2xx_count),
|
||||
},
|
||||
{
|
||||
label: '4xx 请求',
|
||||
color: '#f97316',
|
||||
values: points.map((point) => point.status_4xx_count),
|
||||
},
|
||||
{
|
||||
label: '5xx 请求',
|
||||
color: '#ef4444',
|
||||
values: points.map((point) => point.error_count),
|
||||
values: points.map((point) => point.status_5xx_count),
|
||||
},
|
||||
]}
|
||||
/>
|
||||
|
||||
@@ -1,70 +0,0 @@
|
||||
'use client';
|
||||
|
||||
import type { ReactNode } from 'react';
|
||||
import { FileWarning } from 'lucide-react';
|
||||
import type { UseQueryResult } from '@tanstack/react-query';
|
||||
|
||||
import { useAuth } from '@/components/providers/auth-provider';
|
||||
import { EmptyStateWithBorder } from '@/components/layout/empty';
|
||||
import { ErrorInline } from '@/components/layout/error';
|
||||
import { LoadingStateWithBorder } from '@/components/layout/loading';
|
||||
|
||||
type ErrorPageGateProps = {
|
||||
optionsQuery: UseQueryResult<Array<{ key: string; value: string }>, Error>;
|
||||
children: ReactNode;
|
||||
};
|
||||
|
||||
export function ErrorPageGate({ optionsQuery, children }: ErrorPageGateProps) {
|
||||
const { user, loading: authLoading } = useAuth();
|
||||
|
||||
if (authLoading) {
|
||||
return (
|
||||
<div className='py-6 px-1'>
|
||||
<LoadingStateWithBorder
|
||||
icon={FileWarning}
|
||||
description='加载权限信息...'
|
||||
/>
|
||||
</div>
|
||||
);
|
||||
}
|
||||
|
||||
if (!user?.is_admin) {
|
||||
return (
|
||||
<div className='py-6 px-1'>
|
||||
<EmptyStateWithBorder
|
||||
icon={FileWarning}
|
||||
title='权限不足'
|
||||
description='只有管理员可以访问源站错误页设置。'
|
||||
/>
|
||||
</div>
|
||||
);
|
||||
}
|
||||
|
||||
if (optionsQuery.isLoading) {
|
||||
return (
|
||||
<div className='py-6 px-1'>
|
||||
<LoadingStateWithBorder
|
||||
icon={FileWarning}
|
||||
description='加载错误页配置...'
|
||||
/>
|
||||
</div>
|
||||
);
|
||||
}
|
||||
|
||||
if (optionsQuery.isError) {
|
||||
return (
|
||||
<div className='py-6 px-1'>
|
||||
<ErrorInline
|
||||
message={
|
||||
optionsQuery.error instanceof Error
|
||||
? optionsQuery.error.message
|
||||
: '加载失败'
|
||||
}
|
||||
onRetry={() => void optionsQuery.refetch()}
|
||||
/>
|
||||
</div>
|
||||
);
|
||||
}
|
||||
|
||||
return <>{children}</>;
|
||||
}
|
||||
@@ -1,206 +0,0 @@
|
||||
'use client';
|
||||
|
||||
import Link from 'next/link';
|
||||
import { useEffect, useState } from 'react';
|
||||
import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query';
|
||||
import {
|
||||
ArrowLeft,
|
||||
FileCode2,
|
||||
Loader2,
|
||||
RotateCcw,
|
||||
Save,
|
||||
Sparkles,
|
||||
} from 'lucide-react';
|
||||
import { toast } from 'sonner';
|
||||
|
||||
import { useAuth } from '@/components/providers/auth-provider';
|
||||
import {
|
||||
AlertDialog,
|
||||
AlertDialogAction,
|
||||
AlertDialogCancel,
|
||||
AlertDialogContent,
|
||||
AlertDialogDescription,
|
||||
AlertDialogFooter,
|
||||
AlertDialogHeader,
|
||||
AlertDialogTitle,
|
||||
} from '@/components/ui/alert-dialog';
|
||||
import { Button } from '@/components/ui/button';
|
||||
import {
|
||||
Select,
|
||||
SelectContent,
|
||||
SelectItem,
|
||||
SelectTrigger,
|
||||
SelectValue,
|
||||
} from '@/components/ui/select';
|
||||
import {
|
||||
DEFAULT_ORIGIN_ERROR_PAGE_TEMPLATE_ID,
|
||||
getOriginErrorPageTemplate,
|
||||
ORIGIN_ERROR_PAGE_TEMPLATES,
|
||||
} from '@/lib/openflare/origin-error-page-templates';
|
||||
import { OptionService } from '@/lib/services/openflare';
|
||||
|
||||
import { ErrorPageGate } from '../components/error-page-gate';
|
||||
import { HtmlEditorWorkspace } from '../components/html-editor-workspace';
|
||||
import {
|
||||
invalidateErrorPageQueries,
|
||||
KEY_HTML,
|
||||
mapOptionsToFields,
|
||||
OPTIONS_QUERY_KEY,
|
||||
optionsToMap,
|
||||
validateErrorPageHTML,
|
||||
} from '../components/shared';
|
||||
|
||||
export default function ErrorPageEditPage() {
|
||||
const { user } = useAuth();
|
||||
const queryClient = useQueryClient();
|
||||
const [html, setHtml] = useState('');
|
||||
const [restoreOpen, setRestoreOpen] = useState(false);
|
||||
const [templateId, setTemplateId] = useState(
|
||||
DEFAULT_ORIGIN_ERROR_PAGE_TEMPLATE_ID,
|
||||
);
|
||||
|
||||
const optionsQuery = useQuery({
|
||||
queryKey: OPTIONS_QUERY_KEY,
|
||||
queryFn: () => OptionService.list(),
|
||||
enabled: !!user?.is_admin,
|
||||
});
|
||||
|
||||
useEffect(() => {
|
||||
if (!optionsQuery.data) return;
|
||||
setHtml(mapOptionsToFields(optionsToMap(optionsQuery.data)).html);
|
||||
}, [optionsQuery.data]);
|
||||
|
||||
const saveMutation = useMutation({
|
||||
mutationFn: async () => {
|
||||
validateErrorPageHTML(html);
|
||||
await OptionService.updateBatch([{ key: KEY_HTML, value: html }]);
|
||||
},
|
||||
onSuccess: async () => {
|
||||
toast.success('HTML 模板已保存，请前往版本发布使配置生效');
|
||||
await invalidateErrorPageQueries(queryClient);
|
||||
},
|
||||
onError: (error) => {
|
||||
toast.error(error instanceof Error ? error.message : '保存失败');
|
||||
},
|
||||
});
|
||||
|
||||
const loadSelectedTemplate = () => {
|
||||
const tmpl = getOriginErrorPageTemplate(templateId);
|
||||
if (!tmpl) {
|
||||
toast.error('未找到所选模板');
|
||||
return;
|
||||
}
|
||||
setHtml(tmpl.html);
|
||||
toast.success(`已加载模板「${tmpl.name}」到编辑器`);
|
||||
};
|
||||
|
||||
const restoreDefault = () => {
|
||||
setHtml('');
|
||||
setRestoreOpen(false);
|
||||
toast.success('已清空为使用服务端内置默认模板（需保存后生效）');
|
||||
};
|
||||
|
||||
return (
|
||||
<ErrorPageGate optionsQuery={optionsQuery}>
|
||||
<div className='flex flex-col gap-4 py-6 px-1'>
|
||||
<div className='flex flex-col gap-3 sm:flex-row sm:items-center sm:justify-between'>
|
||||
<div className='flex items-center gap-3'>
|
||||
<Button variant='outline' size='icon' className='h-8 w-8' asChild>
|
||||
<Link href='/error-pages' aria-label='返回错误页'>
|
||||
<ArrowLeft className='size-4' />
|
||||
</Link>
|
||||
</Button>
|
||||
<div className='flex items-center gap-2'>
|
||||
<FileCode2 className='size-5 text-primary' />
|
||||
<div>
|
||||
<h1 className='text-2xl font-semibold tracking-tight'>
|
||||
编辑
|
||||
</h1>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<HtmlEditorWorkspace
|
||||
value={html}
|
||||
onChange={setHtml}
|
||||
toolbarRight={
|
||||
<>
|
||||
<div className='flex items-center gap-1.5'>
|
||||
<span className='text-[11px] text-muted-foreground hidden sm:inline'>
|
||||
内置模板
|
||||
</span>
|
||||
<Select value={templateId} onValueChange={setTemplateId}>
|
||||
<SelectTrigger className='h-7 w-[160px] text-[11px] bg-background'>
|
||||
<SelectValue placeholder='选择模板' />
|
||||
</SelectTrigger>
|
||||
<SelectContent>
|
||||
{ORIGIN_ERROR_PAGE_TEMPLATES.map((tmpl) => (
|
||||
<SelectItem
|
||||
key={tmpl.id}
|
||||
value={tmpl.id}
|
||||
className='text-xs'
|
||||
>
|
||||
{tmpl.name}
|
||||
</SelectItem>
|
||||
))}
|
||||
</SelectContent>
|
||||
</Select>
|
||||
<Button
|
||||
type='button'
|
||||
variant='ghost'
|
||||
size='sm'
|
||||
className='h-7 px-2 text-[11px]'
|
||||
onClick={loadSelectedTemplate}
|
||||
>
|
||||
<Sparkles className='size-3.5' />
|
||||
加载模板
|
||||
</Button>
|
||||
</div>
|
||||
<Button
|
||||
type='button'
|
||||
variant='ghost'
|
||||
size='sm'
|
||||
className='h-7 px-2 text-[11px]'
|
||||
onClick={() => setRestoreOpen(true)}
|
||||
>
|
||||
<RotateCcw className='size-3.5' />
|
||||
恢复默认
|
||||
</Button>
|
||||
<Button
|
||||
size='sm'
|
||||
className='h-7 px-3 text-[11px]'
|
||||
disabled={saveMutation.isPending}
|
||||
onClick={() => saveMutation.mutate()}
|
||||
>
|
||||
{saveMutation.isPending ? (
|
||||
<Loader2 className='size-3 animate-spin' />
|
||||
) : (
|
||||
<Save className='size-3' />
|
||||
)}
|
||||
保存
|
||||
</Button>
|
||||
</>
|
||||
}
|
||||
/>
|
||||
</div>
|
||||
|
||||
<AlertDialog open={restoreOpen} onOpenChange={setRestoreOpen}>
|
||||
<AlertDialogContent>
|
||||
<AlertDialogHeader>
|
||||
<AlertDialogTitle>恢复默认 HTML？</AlertDialogTitle>
|
||||
<AlertDialogDescription>
|
||||
将清空编辑器内容，保存后使用服务端内置默认模板。此操作不会自动保存。
|
||||
</AlertDialogDescription>
|
||||
</AlertDialogHeader>
|
||||
<AlertDialogFooter>
|
||||
<AlertDialogCancel>取消</AlertDialogCancel>
|
||||
<AlertDialogAction onClick={restoreDefault}>
|
||||
确认恢复
|
||||
</AlertDialogAction>
|
||||
</AlertDialogFooter>
|
||||
</AlertDialogContent>
|
||||
</AlertDialog>
|
||||
</ErrorPageGate>
|
||||
);
|
||||
}
|
||||
@@ -1,211 +0,0 @@
|
||||
'use client';
|
||||
|
||||
import Link from 'next/link';
|
||||
import { useEffect, useMemo, useState } from 'react';
|
||||
import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query';
|
||||
import {
|
||||
Expand,
|
||||
FileWarning,
|
||||
Loader2,
|
||||
Pencil,
|
||||
Save,
|
||||
} from 'lucide-react';
|
||||
import { toast } from 'sonner';
|
||||
|
||||
import { useAuth } from '@/components/providers/auth-provider';
|
||||
import { Button } from '@/components/ui/button';
|
||||
import {
|
||||
Card,
|
||||
CardContent,
|
||||
CardDescription,
|
||||
CardHeader,
|
||||
CardTitle,
|
||||
} from '@/components/ui/card';
|
||||
import { Label } from '@/components/ui/label';
|
||||
import { Switch } from '@/components/ui/switch';
|
||||
import { TagsInput } from '@/components/ui/tags-input';
|
||||
import { previewOriginErrorPageHTML } from '@/lib/openflare/default-origin-error-page-html';
|
||||
import {
|
||||
validateStatusCodeTagMessage,
|
||||
validateStatusCodeTags,
|
||||
} from '@/lib/openflare/status-code-tags';
|
||||
import { OptionService } from '@/lib/services/openflare';
|
||||
|
||||
import { ErrorPageGate } from './components/error-page-gate';
|
||||
import {
|
||||
defaultErrorPageFields,
|
||||
invalidateErrorPageQueries,
|
||||
KEY_ENABLED,
|
||||
KEY_STATUS_CODES,
|
||||
mapOptionsToFields,
|
||||
OPTIONS_QUERY_KEY,
|
||||
optionsToMap,
|
||||
type ErrorPageFields,
|
||||
} from './components/shared';
|
||||
|
||||
export default function ErrorPagesPage() {
|
||||
const { user } = useAuth();
|
||||
const queryClient = useQueryClient();
|
||||
const [fields, setFields] = useState<ErrorPageFields>(defaultErrorPageFields);
|
||||
const [tagError, setTagError] = useState<string | null>(null);
|
||||
|
||||
const optionsQuery = useQuery({
|
||||
queryKey: OPTIONS_QUERY_KEY,
|
||||
queryFn: () => OptionService.list(),
|
||||
enabled: !!user?.is_admin,
|
||||
});
|
||||
|
||||
useEffect(() => {
|
||||
if (!optionsQuery.data) return;
|
||||
setFields(mapOptionsToFields(optionsToMap(optionsQuery.data)));
|
||||
setTagError(null);
|
||||
}, [optionsQuery.data]);
|
||||
|
||||
const previewSrcDoc = useMemo(
|
||||
() => previewOriginErrorPageHTML(fields.html),
|
||||
[fields.html],
|
||||
);
|
||||
|
||||
/** 仅保存启用开关 + 触发状态码（HTML 在编辑页单独保存） */
|
||||
const savePolicyMutation = useMutation({
|
||||
mutationFn: async () => {
|
||||
validateStatusCodeTags(fields.statusCodes);
|
||||
await OptionService.updateBatch([
|
||||
{ key: KEY_ENABLED, value: String(fields.enabled) },
|
||||
{
|
||||
key: KEY_STATUS_CODES,
|
||||
value: JSON.stringify(fields.statusCodes),
|
||||
},
|
||||
]);
|
||||
},
|
||||
onSuccess: async () => {
|
||||
toast.success('触发策略已保存，请前往版本发布使配置生效');
|
||||
await invalidateErrorPageQueries(queryClient);
|
||||
},
|
||||
onError: (error) => {
|
||||
toast.error(error instanceof Error ? error.message : '保存失败');
|
||||
},
|
||||
});
|
||||
|
||||
const handleValidateTag = (tag: string) => {
|
||||
const message = validateStatusCodeTagMessage(tag);
|
||||
if (message) {
|
||||
setTagError(message);
|
||||
toast.error(message);
|
||||
return message;
|
||||
}
|
||||
setTagError(null);
|
||||
return null;
|
||||
};
|
||||
|
||||
return (
|
||||
<ErrorPageGate optionsQuery={optionsQuery}>
|
||||
<div className='flex flex-col gap-6 py-6 px-1'>
|
||||
<div className='flex items-center gap-2'>
|
||||
<FileWarning className='size-5 text-primary' />
|
||||
<div>
|
||||
<h1 className='text-2xl font-semibold tracking-tight'>错误页</h1>
|
||||
<p className='text-sm text-muted-foreground'>
|
||||
配置源站/网关错误响应时的统一 HTML
|
||||
页面。策略与模板保存后需发布配置版本后生效。
|
||||
</p>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<Card className='border-dashed shadow-none'>
|
||||
<CardHeader className='flex flex-row items-center justify-between gap-4'>
|
||||
<div>
|
||||
<CardTitle className='text-base'>启用源站错误页</CardTitle>
|
||||
<CardDescription>
|
||||
关闭后会透传源站或 Nginx 默认错误响应。
|
||||
</CardDescription>
|
||||
</div>
|
||||
<Switch
|
||||
checked={fields.enabled}
|
||||
onCheckedChange={(enabled) =>
|
||||
setFields((prev) => ({ ...prev, enabled }))
|
||||
}
|
||||
aria-label='启用源站错误页'
|
||||
/>
|
||||
</CardHeader>
|
||||
</Card>
|
||||
|
||||
<Card className='border-dashed shadow-none'>
|
||||
<CardHeader className='flex flex-col gap-3 sm:flex-row sm:items-start sm:justify-between space-y-0'>
|
||||
<div className='space-y-1.5'>
|
||||
<CardTitle className='text-base'>触发状态码</CardTitle>
|
||||
<CardDescription>
|
||||
支持单码（如 502）或闭区间（如 500-599），范围
|
||||
400–599。默认 500-599。修改启用开关或状态码后需点击保存。
|
||||
</CardDescription>
|
||||
</div>
|
||||
<Button
|
||||
size='sm'
|
||||
className='shrink-0'
|
||||
disabled={savePolicyMutation.isPending}
|
||||
onClick={() => savePolicyMutation.mutate()}
|
||||
>
|
||||
{savePolicyMutation.isPending ? (
|
||||
<Loader2 className='size-3.5 animate-spin' />
|
||||
) : (
|
||||
<Save className='size-3.5' />
|
||||
)}
|
||||
保存
|
||||
</Button>
|
||||
</CardHeader>
|
||||
<CardContent className='flex flex-col gap-2'>
|
||||
<Label htmlFor='origin-error-status-codes' className='sr-only'>
|
||||
状态码标签
|
||||
</Label>
|
||||
<TagsInput
|
||||
id='origin-error-status-codes'
|
||||
value={fields.statusCodes}
|
||||
onChange={(statusCodes) => {
|
||||
setFields((prev) => ({ ...prev, statusCodes }));
|
||||
setTagError(null);
|
||||
}}
|
||||
validateTag={handleValidateTag}
|
||||
placeholder='例如 502 或 500-599，回车添加'
|
||||
aria-invalid={!!tagError}
|
||||
/>
|
||||
{tagError ? (
|
||||
<p className='text-xs text-destructive'>{tagError}</p>
|
||||
) : (null)}
|
||||
</CardContent>
|
||||
</Card>
|
||||
|
||||
<Card className='border-dashed shadow-none overflow-hidden'>
|
||||
<CardHeader className='flex flex-row items-start justify-between gap-3 space-y-0'>
|
||||
<div className='space-y-1.5'>
|
||||
<CardTitle className='text-base'>页面预览</CardTitle>
|
||||
</div>
|
||||
<div className='flex shrink-0 flex-wrap gap-2'>
|
||||
<Button variant='outline' size='sm' asChild>
|
||||
<Link href='/error-pages/preview'>
|
||||
<Expand className='size-3.5' />
|
||||
预览
|
||||
</Link>
|
||||
</Button>
|
||||
<Button size='sm' asChild>
|
||||
<Link href='/error-pages/edit'>
|
||||
<Pencil className='size-3.5' />
|
||||
编辑
|
||||
</Link>
|
||||
</Button>
|
||||
</div>
|
||||
</CardHeader>
|
||||
<CardContent>
|
||||
<div className='overflow-hidden rounded-md border bg-muted/30'>
|
||||
<iframe
|
||||
title='源站错误页预览'
|
||||
sandbox=''
|
||||
srcDoc={previewSrcDoc}
|
||||
className='h-[32rem] w-full bg-background'
|
||||
/>
|
||||
</div>
|
||||
</CardContent>
|
||||
</Card>
|
||||
</div>
|
||||
</ErrorPageGate>
|
||||
);
|
||||
}
|
||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user