netbox-review-integration

NetBox 集成代码审查

你对 NetBox API 的了解可能已经过时。 在指出问题之前，请根据当前文档核实具体的 API 行为、限制和模式。

目标： NetBox 4.5–4.7（当前为 4.7.3）。部分规则在 4.6 和 4.7 之间有所变化——应用带版本标记的规则之前，请先确定目标版本（GET /api/status/ → netbox-version，或项目指定的版本）。

检索来源

来源	URL / 方法	用途
NetBox REST API 文档	https://netboxlabs.com/docs/netbox/integrations/rest-api/	当前端点行为
pynetbox 仓库	https://github.com/netbox-community/pynetbox	SDK 方法签名
Diode Python SDK	https://github.com/netboxlabs/diode-sdk-python	Ingestion API 模式
NetBox MCP 服务	如果已配置——核实对象架构和筛选条件是否可用	字段验证

审查工作流

审查 NetBox 集成代码时，请遵循此检查清单：

1. 核实检索信息 — 对不确定的端点或模式，查阅当前 API 文档
2. 阅读完整文件 — 在指出问题之前，先了解集成的意图
3. 检查身份验证 — 令牌格式、请求头用法、凭据存储
4. 检查分页 — 所有列表端点都必须处理分页
5. 检查性能 — config_context 处理（取决于版本）、brief 模式 / 字段选择、筛选条件的具体程度
6. 检查错误处理 — HTTP 错误、速率限制、超时、部分失败
7. 检查数据完整性 — 正确使用 PATCH 与 PUT、批量操作的原子性
8. 提供证据 — 引用具体行号并说明问题所在

关键规则

身份验证（AUTH）

ID	规则	严重程度
AUTH-1	在 NetBox 4.5+ 上使用带 nbt_ 前缀的 v2 令牌	高
AUTH-2	切勿在源代码中硬编码令牌——使用环境变量或密钥管理器	严重
AUTH-3	在 Authorization 请求头中使用 Bearer 前缀（4.5+ 不使用 Token）	高
AUTH-4	核实令牌对所有访问的端点都具备所需权限	中
AUTH-5	指出对 v1（Token <plaintext>）令牌的依赖——该令牌在 4.6 中弃用，并在 v5.0 中移除；请迁移至 v2。在 4.6.1+ 中，创建时仅显示一次 v2 明文值，位于响应的 token 字段（key 只是公开标识符）——届时请保存该值	高
AUTH-6	切勿使用 ?background=true 创建令牌（4.7.0/4.7.1 会将明文记录在作业结果中；4.7.2 会返回 400）；创建时也切勿依赖客户端指定的 token 值（4.7+ 会忽略该值）	高
AUTH-7	在 4.7+ 上通过 POST /api/extras/scripts/<id>/ 执行自定义脚本需要可写令牌——请指出用于此操作的只读令牌	中

分页（PAG）

ID	规则	严重程度
PAG-1	所有列表端点调用都必须处理分页（跟随 next 链接）	严重
PAG-2	切勿假设所有结果都能放入单个响应中——即使是较小的集合也会不断增长	高
PAG-3	设置明确的 limit 参数——不要依赖服务器默认值（50）	中
PAG-4	GraphQL 查询在每个列表层级都必须包含 pagination: {limit: N}	严重
PAG-5	嵌套的 GraphQL 列表需要各自的分页参数	高
PAG-6	对大量读取，优先使用游标分页而非较大的偏移量——REST 使用 ?start=<id>（4.6+），GraphQL 使用 pagination: {start: N, limit: M}（4.5.2+）；请指出较大的 ?offset= 扫描	中

性能（PERF）

ID	规则	严重性
PERF-1	**4.5–4.6：**设备/虚拟机列表查询必须发送 ?omit=config_context（4.5.2+）或 ?exclude=config_context。**4.7.0–4.7.2：**配置上下文会缓存并始终加载；?exclude= 会被静默忽略——不要因缺少该参数而标记；应标记依赖它缩减负载大小的代码，并建议使用 ?fields=/?omit=/?brief=True。4.7.3+：?omit=config_context/?fields=/?brief=True 会再次跳过配置上下文数据库注解——应标记加载了未使用的 config_context 的列表读取。所有 4.7.x 版本中的 ?exclude= 都无效；?omit=config_context 是兼容各版本的写法	严重（4.5–4.6）/低（4.7.0–4.7.2）/中（4.7.3+）
PERF-2	对引用查询和下拉列表使用 ?brief=True	高
PERF-3	大规模操作时使用特定筛选器（name__ic=、site_id=），而不是 ?q=	高
PERF-4	使用 ?fields= 仅选择所需字段	中
PERF-5	并行执行相互独立的 API 调用——不要串行发送无关请求	中
PERF-6	使用批量端点（POST/PATCH/DELETE 数组），而不是逐个对象调用	高
PERF-7	GraphQL 深度必须保持在 ≤ 3，绝不能超过 5	高

错误处理（ERR）

ID	规则	严重性
ERR-1	处理 HTTP 4xx/5xx 响应——不要假定操作成功	严重
ERR-2	对 429（速率限制）和 5xx 错误实现带退避的重试机制	高
ERR-3	处理批量操作失败——所有版本均非全有或全无。4.7+ 的响应正文为 {"detail", "errors": [{"index" or "id", "errors"}]}：将错误映射回提交的对象（创建和格式错误的条目使用 index，更新/删除使用 id），并仅重新提交失败对象；4.5–4.6 仅返回首个失败项的字段错误	中
ERR-4	检查 Diode 数据导入响应中的 response.errors	高
ERR-5	处理分支异步任务失败（轮询直到状态终结）	高
ERR-6	?background=true（4.7+）：202 表示已接受，而非已成功——代码必须轮询 job.url，直到状态终结，并检查 data.status_code。应标记将 202 视为成功、将 If-Match 与后台处理结合使用（400）、缺少 503 处理（无工作进程），以及在 4.7.0–4.7.2 中将 ?background=true 与 X-NetBox-Branch 结合使用（标头会被丢弃；写入会落到主分支；已在 4.7.3 修复）	高

数据完整性（DATA）

ID	规则	严重性
DATA-1	更新时使用 PATCH——PUT 会替换整个对象并清除未提供的字段	严重
DATA-2	批量 PATCH/DELETE 操作中的每个对象都包含 id	高
DATA-3	为提高可读性使用自然键（slug/name），但须注意唯一性约束	中
DATA-4	验证 REST 创建操作的依赖顺序（先创建父项，再创建子项）	高
DATA-5	IPAddress 值必须包含 CIDR 前缀长度（/24，不能只提供 IP）	高
DATA-6	编辑标签时，优先使用只写的 add_tags/remove_tags（4.6+），而不是对完整 tags 列表执行读取-修改-写入——后者会覆盖并发写入者添加的标签	中
DATA-7	并发情况下对单个对象执行读取-修改-写入时，使用 ETag + If-Match（4.6+）；412 响应表示对象已更改——应重新获取并重试，而不是盲目覆盖	中
DATA-8	在 4.7+ 中，选择/多选自定义字段会以 {"value", "label"} 对象的形式读取——应标记 custom_fields["x"] == "raw" 这类比较，以及将读取到的对象写回的代码（会导致验证失败）；写入原始值	高
DATA-9	服务：在 4.7+ 中使用 port_mappings（["tcp/80"]），而不是已弃用的 protocol/ports 参数对（将在 5.0 中移除）；应标记 protocol__ic 这类筛选器和 port__empty 筛选器（已在 4.7 中移除）	中

应标记的反模式

反模式	重要原因	修复方法
没有分页循环	会静默丢弃第一页之后的数据	持续跟随 next 链接，直到其值为 null
使用 ?q= 进行批量筛选	全文搜索在大规模数据下速度很慢	使用具体的筛选表达式
使用 PUT 进行部分更新	会清除你不打算更改的字段	使用 PATCH
在源代码中硬编码令牌	存在安全漏洞	使用环境变量
逐个创建对象，而非批量创建	速度慢 100 倍	对列表端点使用数组 POST
在不会使用 config_context 的列表查询中加载它	在 4.5–4.6 上会慢 10–100 倍；在 4.7.3+ 上会增加额外的数据库注解；仅在 4.7.0–4.7.2 上会造成负载膨胀	添加 ?omit=config_context（4.5.2+，跨版本兼容）；?exclude= 仅适用于 4.5–4.6，在所有 4.7.x 版本上都会被忽略
将 ?background=true 返回的 HTTP 202（4.7+）视为成功	验证和写入操作稍后才会在工作进程中执行	轮询作业 URL；检查 status 和 data.status_code
在 4.7+ 上使用 custom_fields["env"] == "prod"	选择值是 {"value", "label"} 字典，因此比较结果始终为 False	比较 ["value"]；混合使用 4.6/4.7 的部署环境中应谨慎解包
使用 ?background=true 创建 API 令牌	明文会进入作业结果（4.7.0/4.7.1）；在 4.7.2+ 上返回 400	同步创建令牌；运行 ≥ 4.7.3（4.7.0/4.7.1 会泄露令牌；4.7.3 增加了分支安全的后台写入和 config-context 忽略优化）
在 4.7.0–4.7.2 上同时发送 ?background=true 和 X-NetBox-Branch	工作进程会丢弃分支标头，导致批量写入落入 main（或被 Changes 的 protect_main 拒绝）	在 ≤ 4.7.2 上的分支上下文中使用同步批量写入；4.7.3+ 会正确传递标头
在 API 调用中捕获裸 Exception	会隐藏真实错误	专门捕获 requests.HTTPError
HTTP 请求未设置超时	网络出现问题时会无限期挂起	设置 timeout=30
GraphQL 未提供分页参数	省略 pagination 会返回所有行；设置 pagination 却不指定 limit 会返回 Strawberry 的默认值 100（而非 REST 的默认值 50）——两者都可能静默地与预期不符	始终显式传递 pagination: {limit: N}
轮询分支作业时不使用退避	浪费 API 调用，且可能触发速率限制	使用指数退避（1s → 30s）

版本说明

NetBox 4.7.3（2026-10-13）

• PERF-1 的严重性升为中等：?omit=config_context/?fields=/?brief=True 会再次跳过 config-context 数据库注解（?exclude= 仍然无效）。ERR-6 的分支限制已消除：现在 ?background=true 会将 X-NetBox-Branch 传递到工作进程。建议使用 ≥ 4.7.3（4.7.0/4.7.1 会泄露令牌；4.7.3 增加了分支安全的后台写入和 config-context 忽略优化）。

范围

此技能涵盖调用 NetBox API 的代码。不涵盖：

• NetBox 插件内部实现 → 使用 netbox-plugin-development
• 数据模型设计质量 → 使用 netbox-review-datamodel
• NetBox 服务端管理 → 使用 netbox-administration

原则

• 确保准确。 标记版本相关问题前，先查阅当前 API 文档。
• 提供证据。 引用行号并说明实际故障原因。
• 关注正确性。 能正常工作的集成即使略显冗长，也胜过巧妙却无法运行的集成。
• 严重性很重要。 严重问题会导致功能失效。高严重性问题会降低性能或可靠性。中等严重性问题会影响可维护性。
• 不要过度标记。 如果代码在特定用例中能正确运行（例如数据集较小，可在一页内返回），请指出其限制，但不要将其标记为严重问题。