crawlsnap/crawlsnap-go
GitHub: crawlsnap/crawlsnap-go
CrawlSnap 数据智能平台的官方 Go SDK，提供类型化的信誉查询、威胁情报增强与子域名扫描接口封装。
Stars: 0 | Forks: 0
# CrawlSnap Go SDK
[CrawlSnap](https://crawlsnap.com) 数据智能平台的官方 Go 客户端。提供类型化的响应、类型化的错误、自动重试以及按产品划分的 API 版本控制。
## 安装
```
go get github.com/crawlsnap/crawlsnap-go
```
需要 Go 1.23+（paginator 使用了 range-over-func）。
## 认证
从您的控制面板获取 API 密钥并将其传递给 `NewClient`，或者设置 `CRAWLSNAP_API_KEY` 环境变量并传递空字符串。
```
client, err := crawlsnap.NewClient("sk-cs-...") // or NewClient("") with the env var
if err != nil {
log.Fatal(err)
}
```
## 快速开始
```
package main
import (
"context"
"fmt"
"log"
crawlsnap "github.com/crawlsnap/crawlsnap-go"
)
func main() {
client, err := crawlsnap.NewClient("")
if err != nil {
log.Fatal(err)
}
ip, err := client.VectorSnap.IP(context.Background(), "8.8.8.8")
if err != nil {
log.Fatal(err)
}
fmt.Println(ip.GetReputation(), ip.GetAsOwner())
}
```
每次调用成功时会返回解包后的、类型化的 payload，否则返回类型化的错误——您无需亲自检查响应封装。
## 资源
| 调用 | 返回 |
|---|---|
| `client.VectorSnap.URL(ctx, q)` | URL 的信誉增强 |
| `client.VectorSnap.Hash(ctx, q)` | 文件哈希的信誉增强 |
| `client.VectorSnap.IP(ctx, q)` | IP 的信誉增强 |
| `client.VectorSnap.Domain(ctx, q)` | 域名的信誉增强 |
| `client.PulseSnap.URL / Hash / IP / Domain(ctx, q)` | 威胁情报脉冲增强 |
| `client.SubdoSnap.Scan(ctx, q)` | 一页子域名 |
| `client.SubdoSnap.ScanIter(ctx, q)` | 跨越所有页面的全部子域名 |
## 错误
失败时会返回类型化的错误，可通过 `errors.As` 进行排查：
```
ip, err := client.VectorSnap.IP(ctx, "8.8.8.8")
if err != nil {
var nf *crawlsnap.NotFoundError
switch {
case errors.As(err, &nf):
// no data for this indicator
default:
var status *crawlsnap.APIStatusError // any HTTP status error
if errors.As(err, &status) {
log.Printf("status=%d request_id=%s", status.StatusCode, status.RequestID)
}
}
}
```
| 类型 | 状态码 | 含义 |
|---|---|---|
| `BadRequestError` | 400 | 无效的指示器 |
| `AuthenticationError` | 401 | 密钥缺失/无效 |
| `QuotaExceededError` | 402 | 额度或月度配额用尽 |
| `SubscriptionInactiveError` | 403 | 订阅未激活 |
| `NotFoundError` | 404 | 没有该指示器的数据 |
| `RateLimitError` | 429 | 请求达到限制（包含 `RetryAfter`） |
| `ServerError` | 5xx | 服务器/上游故障 |
| `APIConnectionError` | — | 传输失败（DNS / 连接 / TLS） |
| `APITimeoutError` | — | 请求超时（同时也是 `APIConnectionError`） |
`APIStatusError` 可匹配任何状态错误；`CrawlSnapError` 接口可匹配 SDK 返回的任何内容。
## 分页
`ScanIter` 会自动为您追踪游标。在 Go 1.23+ 中使用 range 遍历它：
```
for sub, err := range client.SubdoSnap.ScanIter(ctx, "example.com") {
if err != nil {
log.Fatal(err)
}
fmt.Println(sub["subdomain"])
}
```
如需手动分页，请先使用 `Scan`，然后使用返回的 `Cursor` 调用 `ScanWithCursor`。
## API 版本控制
每个产品均独立进行版本控制。直接调用会使用该产品的**稳定默认**版本（`crawlsnap.DefaultVersion`），当您升级 SDK 时，该版本永远不会自行变动。您可以将某个产品固定到特定版本，而不影响其他产品：
```
client.VectorSnap.IP(ctx, "8.8.8.8") // stable default version
client.VectorSnap.V1().IP(ctx, "8.8.8.8") // explicitly VectorSnap v1
client.PulseSnap.Domain(ctx, "example.com") // unaffected — PulseSnap default
```
## 配置
```
client, err := crawlsnap.NewClient("sk-cs-...",
crawlsnap.WithBaseURL("https://api.crawlsnap.com"), // or $CRAWLSNAP_BASE_URL
crawlsnap.WithTimeout(30*time.Second),
crawlsnap.WithMaxRetries(3), // 429 / 5xx / connection
crawlsnap.WithHTTPClient(myHTTPClient), // advanced
)
```
重试机制采用带抖动的指数退避策略，并在遇到 429 错误时遵从 `Retry-After` 响应头。
## 原始响应
在获取类型化返回结果的同时，捕获完整的封装信息（状态、标头、请求 ID）：
```
var raw crawlsnap.RawResponse
ip, err := client.VectorSnap.IP(ctx, "8.8.8.8", crawlsnap.WithRawResponse(&raw))
// raw.StatusCode, raw.RequestID, raw.Headers, raw.IsSuccess, raw.Data
```
## 开发
`models/` 中的类型化模型是根据公开的 OpenAPI 契约生成的；facade 为手写代码。在契约变更后重新生成模型：
```
./scripts/regenerate.sh # re-bundles the contract and regenerates models/ only
go test ./...
```
## 发布
发布版本即为 git 标签——推送 `vX.Y.Z` 标签会将该模块发布到 Go 代理（无需单独上传到注册中心）。使用以下辅助工具：
```
./scripts/release.sh 0.2.0 # bumps version.go, runs checks, commits, tags, pushes, gh release
```
标签是不可变的：要修复错误的发布，请发布一个新的补丁版本。`v2` 及以上的版本还需要在 `go.mod` 中添加 `/v2` 模块路径后缀。
## 许可证
[MIT](LICENSE)
标签：API客户端, EVTX分析, Go, Ruby工具, 威胁情报, 开发者工具, 数据智能, 日志审计