golang如何调用Notion API_golang Notion API调用方法-Golang-PHP中文网

Notion API客户端必须配置有效Integration令牌并传入context，否则返回401或context deadline exceeded；令牌需从notion.so/my-integrations创建并共享至目标空间，且所有方法首参必须为非nil context。

golang如何调用notion api_golang notion api调用方法

notionapi

客户端能直接用，但不配好集成令牌和上下文就必然 401 Unauthorized 或 context deadline exceeded —— 这不是代码写得不对，是初始化漏了关键约束。

初始化 client 时必须传入有效 integration token

Notion API 不接受个人 token，只认「Integration」类型令牌。你得在 https://www.notion.so/my-integrations 创建一个 integration，把它 share 到目标 workspace 和 page/database，再复制 Token（以 secret_ 开头）。

常见错误：

误用 Notion 账户的 session token（浏览器 Cookie 里的 token_v2），它不能用于 API
token 复制完整（共 60+ 字符），中间没空格或换行
忘记在 integration 页面把目标 database 或 page 手动 share 给该 integration

初始化示例：

client := notionapi.NewClient("secret_xxx...")

`Page.Get` 和 `Database.Query` 必须带 `context.Context`

所有方法第一个参数都是 context.Context，不能传 nil，否则 panic。多数场景用 context.Background() 即可，但生产环境建议加 timeout：

context.WithTimeout(context.Background(), 5*time.Second) 防止网络卡住整个 goroutine
调用 Database.Query 时若不设 page_size，默认只返回 100 条，大库容易漏数据
Page.Get 返回的 Page 结构体里，Properties 是 map[string]notionapi.PropertyValue，需按 type 字段二次解析（比如 title、select、date 的结构完全不同）

写操作（CreatePage / UpdatePage）要严格匹配 schema

Notion 对 block 和 property 的字段校验极严。例如：

Golang Uber Dig

使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器，提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象，支持命名依赖等

下载

往 database 里 CreatePage 时，Properties 字段名必须和 database 的 property 名**完全一致**（区分大小写、空格、emoji）
Title 类型 property 要传 notionapi.TitleProperty{Title: []notionapi.RichText{{Text: notionapi.Text{Content: "xxx"}}}}，少一层嵌套就 400 Bad Request
更新已有 page 时，UpdatePage 不支持 patch，必须传全量 Properties，否则未传字段会被清空

错误处理别只看 `err != nil`

notionapi 的 error 多数是 HTTP 错误包装，需用类型断言提取真实状态码：

if err != nil {
    var e *notionapi.ErrorResponse
    if errors.As(err, &e) {
        fmt.Printf("Notion API error: %d %s", e.Code, e.Message)
        // e.Code 可能是 "validation_error"、"object_not_found"、"rate_limited" 等
    }
}

特别注意：rate_limited 错误不会自动重试，得自己加 retry 逻辑；object_not_found 常因 page_id 写错或权限没开全导致，不是接口问题。

最常被跳过的点：database query 返回的 Results 是 slice，但 NextCursor 非空时说明还有数据，不手动分页就拿不全——这个字段不在 error 里，也不报错，只是静默截断。