AI导哈

数据合约生成器

Go库，用于从可摄取文件（CSV、JSON/NDJSON、Excel）生成数据合约并计算结构指纹，帮助数据摄取平台在编写管道代码前了解文件结构和身份。

  • by JacobJNilsson
  • Go
  • 本地部署
  • 更新于
在 GitHub 查看 JacobJNilsson/ingestion-contract-mcp

使用说明

数据契约生成器

Go库，用于从可摄入文件（CSV、JSON/NDJSON、Excel）生成数据契约并计算结构指纹。数据摄取平台在为其编写管道代码之前使用它来了解已着陆文件的形状和身份。

安装

go get github.com/JacobJNilsson/data-contract-generator@latest

包裹

包装 用途
contract 共享类型： DataContract, SchemaContract, FieldDefinition, FieldProfile
profile 共享分析核心：类型分类、列分析、值形状签名
csvcontract 分析CSV文件：编码、分隔符、标头检测、类型推断、数据分析
excelcontract 分析Excel（.xlsx）文件：多表、表和标题检测、类型推理、数据分析
jsoncontract 分析JSON数组和NDJSON：流式传输、类型推理、数据分析
fingerprint 结构指纹：管道缓存的规范模式标识、哈希和近邻排名

快速开始

package main

import (
    "context"
    "encoding/json"
    "fmt"
    "log"

    "github.com/JacobJNilsson/data-contract-generator/csvcontract"
)

func main() {
    contract, err := csvcontract.AnalyzeFile(context.Background(), "data.csv", nil)
    if err != nil {
        log.Fatal(err)
    }
    b, _ := json.MarshalIndent(contract, "", "  ")
    fmt.Println(string(b))
}

发展

需要Go 1.25+和 golangci-lint.

大门分为两层：

  • 快速层（默认） --纯Go，没有Docker，没有网络。这就是 make check 以及预提交挂钩运行，以及贡献者每天需要什么。
  • 集成层 --用于必须在实时Postgres上运行的目标代码。被关在后面 integration 构建标签，使其永远不会触及快速路径，并单独运行（在CI中，并在本地按需运行）。它需要一个Docker守护进程（ internal/pgtest harness通过testcontainers启动一次性Postgres）或通过以下方式启动现有数据库 TEST_PG_CONN当两者都不存在时，它会跳过而不是失败。
make setup             # configure git hooks
make check             # fast tier: tidy, vet, lint, test, build (no Docker)
make integration-test  # integration tier: go test -tags=integration ./... (needs Docker or TEST_PG_CONN)

预提交钩子运行 make check 其强制执行每个包裹的覆盖范围：

包装 覆盖门
配置文件 100%
csv合同 100%
指纹 100%
odcs 100%
odcsemission 100%
odcsdest 100%
pgcheck 100%
pginspect 100%
取消导入 100%
jsoncontract 95%
超出合同 95%

pgcontract 在集成层而不是快速层中被100%门控：它的忠实生成器(Generate)需要一个实时的Postgres，因此它的完整行为——纯汇编/验证核心和实时数据库读取相似——是在 -tags=integration 而不是伪造以达到快速的等级。

CI将快速层和集成层作为单独的作业运行，因此纯Go承诺适用于默认路径，而目标代码仍由真正的Postgres覆盖。这两个作业都强制执行上述每个包的覆盖范围门（纯包的快速层，纯包的集成层） pgcontract).

建筑学

contract/        ← shared types (DataContract, SchemaContract, FieldProfile)
profile/         ← shared profiling core: type classification, column profiling, value-shape signatures
csvcontract/     ← CSV file analysis
excelcontract/   ← Excel (.xlsx) file analysis
jsoncontract/    ← JSON/NDJSON file analysis
fingerprint/     ← structural identity for the pipeline cache

excelcontract 发射 contract.DataContract，而 csvcontract 和 jsoncontract 发射自己的 SourceContract 形状，所以 contract/ 是模式样式路径的共享类型集，而不是每个包中的单一真实来源。 csvcontract 和 excelcontract 分享 profile/ 核心； jsoncontract 它有自己的特征，是一个已知的分歧。没有循环依赖关系。

当他们提供的独立分析产品关闭时，独立的源代码分析包（REST/OpenAPI、PostgreSQL、Supabase）和合同验证和转换映射包被删除；如果需要的话，他们还活在git的历史中。

相关 MCP