Voskan/BatchWeaver

# BatchWeaver [](https://github.com/Voskan/BatchWeaver/actions/workflows/ci.yml) [](https://github.com/Voskan/BatchWeaver/actions/workflows/codeql.yml) [](https://pkg.go.dev/github.com/Voskan/BatchWeaver@v1.0.1) [](LICENSE) BatchWeaver 是一个证明门控的批处理编译器和类型化请求合并 Go runtime。它能发现受支持的标量访问模式（包括常见的 N+1 查询形态），证明其安全条件，预览确定性变更，并在有界批次中执行兼容的调用，且不会静默越过请求、租户、授权、事务或会话边界。 ## 为什么选择 BatchWeaver？ 手写的批处理可以减少后端往返次数，但修改标量代码也可能会改变求值顺序、错误标识、取消逻辑、截止时间、结果映射和隔离性。BatchWeaver 将这些行为视为证明义务，而非实现细节。 - **转换前先证明。** 未知或不支持的行为将被拒绝。 - **变更前先覆盖。** 扫描、证明、规划、比对、构建和测试均可在不更改源文件的情况下运行。 - **类型化库契约。** 泛型请求、结果、提供者和声明避免了面向应用程序的代码使用反射。 - **显式隔离。** Scope 和 partition 契约将不兼容的工作排除在同一批次之外。 - **默认失败的发布工具。** 校验和、SBOM、来源、兼容性和发布门控在与发布分离的情况下进行验证。 - **无隐藏遥测。** 工作负载配置文件排除了原始键、有效载荷、凭据、租户标识符和源。 BatchWeaver 不保证每个 Go 调用都可以被批处理，也不保证批处理总是能提升性能。不支持的模式将保持标量执行，或者被拒绝并附带诊断信息。 ## 安装 Go 1.26.x 是受测试的支持窗口：1.26.0 是最低版本，1.26.5 是当前固定的发布工具链。 安装 CLI 或在不可变的 beta 版本中添加类型化库： ``` go install github.com/Voskan/BatchWeaver/cmd/batchweaver@v1.0.1 go get github.com/Voskan/BatchWeaver@v1.0.1 ``` 对于相同版本的源码检出： ``` git clone https://github.com/Voskan/BatchWeaver.git cd BatchWeaver git checkout v1.0.1 make build ./bin/batchweaver version ./bin/batchweaver doctor ``` 包文档和导入示例可通过 [pkg.go.dev](https://pkg.go.dev/github.com/Voskan/BatchWeaver@v1.0.1) 获取。有关库和 CLI 的安装路径，请参阅 [将 BatchWeaver 作为 Go 模块使用](docs/guides/use-as-go-module.md)。 ## 使用 Go package 通过一个类型化的、可静态发现的值来声明标量函数及其兼容的批处理提供者： ``` package users import ( "context" batchweaver "github.com/Voskan/BatchWeaver" "github.com/Voskan/BatchWeaver/operation" ) type User struct { ID int Name string } func loadUser(ctx context.Context, id int) (User, error) { // Scalar implementation. return User{ID: id}, nil } func loadUsers( ctx context.Context, req batchweaver.BatchRequest[int], ) (batchweaver.BatchResponse[User], error) { values := make([]User, req.Len()) for i, item := range req.Items() { values[i] = User{ID: item.Key} } return batchweaver.OrderedOutcomes(req, values) } var GetUser = batchweaver.MustDeclareFunction( operation.MustNewSpec( operation.MustParseID("users.get"), operation.ReadOnly(), operation.WithOrderedResults(), operation.WithRequestScope(), ), loadUser, loadUsers, ) ``` 此声明不会启动 goroutine、注册全局状态或修改源代码。runtime API 是可选的；请参阅 [runtime 指南](docs/guides/runtime-api.md) 和经过编译测试的 [声明示例](examples/declarations/basic)。 ## 五分钟工作流 ``` # 检查支持的命令并验证配置。 batchweaver help batchweaver config validate --file examples/configuration/batchweaver.yaml # 发现并证明 candidates 而不修改 source。 batchweaver scan ./... batchweaver prove ./... # 审查 deterministic plan 和 diff。 batchweaver transform plan ./... batchweaver transform diff ./... # 通过 overlay 测试转换后的代码。 batchweaver test -- -race ./... ``` 物化是一个独立的、显式的操作，提供备份、恢复和回退支持。从[经验证的批处理教程](docs/tutorials/verified-batching.md)开始。 ## 架构 ``` flowchart LR A["Go source and config"] --> B["Package loading and static analysis"] B --> C["Semantic proof obligations"] C -->|"proven"| D["Versioned transformation plan"] C -->|"unknown or unsafe"| R["Reject with diagnostic"] D --> E["Preview and build overlay"] E --> F["Transformed tests"] F -->|"explicit approval"| G["Optional materialization"] E --> H["Typed bridge and runtime"] H --> I["Partitioned batch provider"] ``` 编译器是保守的：证明证书是版本化的，源锚点在使用前会进行检查，转换后的构建默认使用覆盖，并且 runtime 在将提供者结果返回给调用者之前会对其进行验证。 阅读[架构概述](docs/architecture/overview.md)、 [包边界](docs/architecture/package-boundaries.md) 和 [安全模型](docs/concepts/batching-model.md)。 ## 已实现的功能 - 类型化的操作、请求、响应、partition、调度、重试和回退契约； - 显式的请求范围 runtime 合并，具有有界队列、独立取消、截止时间、去重、记忆化和结果验证； - Go 包加载、SSA、保守的调用图/效应分析、候选项发现和确定性报告； - 语义证明证书以及通过构建覆盖实现的静态循环预取/runtime 降级转换； - 精确/复合键 PostgreSQL 读取合成，带有有界的至多一个连接，编译时检查的 SQL 绑定覆盖，`database/sql`，Redis 映射，显式的 HTTP/OpenAPI 批处理，GraphQL 波次分析，以及 gRPC 契约； - 默认分支上提供类型化的 pgx v5、go-redis v9、gqlgen 和 grpc-go 集成包，并附带 pgxmock、miniredis、public-extension 和 bufconn 测试； - 隐私安全的自适应分析、公平性、过载控制、递归波次以及有界的 shadow/active 调优； - 独立的 LSP、可选的 gopls 代理、VS Code 扩展，以及一个安全的 workspace 守护进程，为 CLI/编辑器请求提供有界的共享分析缓存； - 确定性的发布归档、校验和、SPDX/CycloneDX SBOM、本地来源、兼容性报告以及非发布版本验证。 ## 重要限制 - `bridge` 和四个 `adapters/*` 客户端包是实验性的：它们包含在 `v1` 模块中，但不受 `v1` 兼容性承诺的约束，因为它们跟踪第三方的客户端 API。 - 发布的制品带有校验和、SBOM 文档且可复现，但它们**没有经过加密签名**，也不包含托管构建证明。 - 客户端集成由密封的模拟对象覆盖，未经过实时的 PostgreSQL 或 Redis Cluster 验收测试。 - SQL 合成仅限于有文档记录的精确/复合键 PostgreSQL 读取以及一个显式的至多一个 INNER/LEFT 连接；写入、一对多连接和任意 SQL 重写将被拒绝。 - GraphQL/gRPC 优化需要显式集成；不会推断任意的网络请求合并。 - 编译器和 runtime 制品 schema 仍为 `v1alpha1`；它们是重新生成的，而不是迁移的，且被排除在 `v1` API 承诺之外。 - Linux、macOS 和 Windows 的托管构建在修正后的发布分支上通过。 - VS Code 扩展以 GitHub Release VSIX 的形式提供，而不是通过 Visual Studio Marketplace。 - 校验和已发布，但该 beta 版本没有加密标签或制品签名；请参阅发布说明和验证说明。 参见[已知问题](KNOWN-ISSUES.md) 和详细的 [限制索引](docs/README.md#limitations)。 ## 文档 - [文档网站](https://voskan.github.io/BatchWeaver/docs.html) - [可运行示例](https://voskan.github.io/BatchWeaver/examples.html) - [Go API 和 CLI](https://voskan.github.io/BatchWeaver/api.html) - [已实现的功能和 v1 就绪情况](https://voskan.github.io/BatchWeaver/status.html) - [文档索引](docs/README.md) - [教程](docs/tutorials/verified-batching.md) - [操作指南](docs/guides/scan.md) - [参考](docs/reference/configuration.md) - [架构](docs/architecture/overview.md) - [兼容性](docs/release/compatibility.md) - [安全](SECURITY.md) - [支持](SUPPORT.md) - [贡献](CONTRIBUTING.md) ## 开发 ``` make fmt-check go test ./... go test -race ./... go vet ./... make check ``` 发布保证是非发布性的： ``` make release-snapshot ./bin/batchweaver release verify dist/release-manifest.json ``` ## 项目状态 `v1.0.0` 根据语义化版本控制冻结了 Tier 1 公共 Go API，并提供了从每个已发布的预发布版本进行升级的测试路径。它附带明确接受的风险——未签名的制品、在标记的提交处未观察到托管兼容性证据、较短的公开预发布期以及无实时后端验收——每一项都在 [稳定发布决策](docs/release/v1.0.0/stable-release-decision.md) 和机器可读的 [门控报告](release/gates-v1.0.0.json) 中记录了补救计划。 该项目不声称拥有长期的生产稳定性证据。请参阅 [beta 证据](docs/release/v1.0.0/beta-evidence.md) 和 [后续计划](docs/release/v1.0.0/project-completion.md)。 ## 许可证 Apache License 2.0。请参阅 [LICENSE](LICENSE)、[NOTICE](NOTICE) 和 [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md)。

标签：EVTX分析, Go, Python工具, Ruby工具, SOC Prime, Subfinder, 代码分析, 凭证管理, 开发工具, 性能优化, 搜索引擎查询, 日志审计, 检测绕过, 测试用例, 编译器, 自动批处理