게시된 Go 모듈의 메타데이터를 조회할 수 있는 공식 pkg.go.dev API와 참조 클라이언트인 pkgsite-cli를 소개합니다.
pkg.go.dev는 시작 이후 Go 커뮤니티의 패키지 문서화와 발견을 위한 주요 리소스로 자리 잡았습니다. 초기에는 사용자를 위한 포괄적이고 높은 접근성의 웹 인터페이스를 만드는 데 우선순위를 두었지만, 프로그래밍 방식의 접근 필요성은 점점 더 분명해졌습니다. 도구, IDE 통합, 자동화 워크플로를 구축하는 개발자들은 그동안 이 데이터에 접근하기 위해 웹 스크래핑과 같은 취약한 우회 방법에 의존해 왔습니다. 이러한 변화하는 요구를 더 잘 충족하기 위해, 이제 우리는 커뮤니티가 필요로 하는 정보에 대해 견고하고 직접적인 접근을 제공하도록 플랫폼을 확장하고 있습니다.
오늘 우리는 게시된 Go 모듈의 메타데이터를 조회하기 위한 서비스 인터페이스인 공식 pkg.go.dev API를 소개하게 되어 매우 기쁩니다. 이번 출시는 수년간의 커뮤니티 피드백에 직접적으로 응답한 결과입니다. 더 나아가 AI 지원 코딩의 부상과 함께 정식화된 인터페이스의 필요성은 더욱 커졌습니다. 이제 도구들은 Go 생태계를 더 높은 정밀도로 추론하는 데 필요한 구체적이고 높은 충실도의 컨텍스트에 접근할 수 있습니다.
안정성과 효율적인 캐싱을 위해 설계된 이 API는 상태를 유지하지 않는 GET 전용 아키텍처를 사용합니다. 현재 주요 엔드포인트는 /v1beta 경로 아래에서 호스팅됩니다. 커뮤니티 피드백 수렴과 안정성 확인 기간을 거친 뒤, 정식 v1 릴리스로 전환할 계획입니다.
모든 엔드포인트, 쿼리 매개변수, 응답 형식에 대한 완전한 대화형 참조는 pkg.go.dev/api specification을 확인하세요. 기계가 읽을 수 있는 API 계약도 OpenAPI specification으로 직접 게시되어 있습니다.
| Endpoint | Description |
|---|---|
/v1beta/package/{path} | {path}에 있는 패키지에 대한 정보 |
/v1beta/module/{path} | {path}에 있는 모듈에 대한 정보 |
/v1beta/versions/{path} | {path}에 있는 모듈의 버전 |
/v1beta/packages/{path} | {path}에 있는 모듈의 패키지에 대한 정보 |
/v1beta/search?q={query} | 주어진 쿼리에 대한 검색 결과 |
/v1beta/symbols/{path} | {path}에 있는 패키지가 선언한 심볼 목록 |
/v1beta/imported-by/{path} | {path}에 있는 패키지를 가져오는 패키지의 경로 |
/v1beta/vulns/{path} | {path}에 있는 모듈 또는 패키지의 취약점 |
이 API의 한 가지 설계 원칙은 “편의보다 정밀성”입니다. 맥락을 설명하자면, go mod tidy가 메인 모듈의 기존 의존성이 제공하지 않는 패키지의 import를 만나면 어떤 모듈이 필요한지 결정하기 위해 “가장 긴 모듈 경로” 규칙을 적용합니다. (둘 이상의 모듈이 해당 패키지를 제공할 수 있다는 사실이, 나중에 기존 프로그램을 깨뜨리지 않고 서브모듈을 분리해 낼 수 있게 해 줍니다.) pkg.go.dev 웹 인터페이스도 주어진 패키지 경로에 대해 어떤 패키지를 표시할지 선택할 때 비슷한 관례를 따릅니다. 반면 pkg.go.dev API는 모듈이 모호하지 않게 지정되기를 요구합니다. 패키지 경로가 여러 모듈에 존재해 모호한 경우, API는 후보 목록을 반환하고 클라이언트에게 더 구체적으로 지정하라는 오류를 보고합니다.
예를 들어 example.com/a/b/c로 import되는 패키지는 모듈 example.com/a가 제공할 수도 있고 example.com/a/b가 제공할 수도 있습니다. pkg.go.dev 웹 인터페이스는 “가장 긴 모듈 경로”(example.com/a/b)를 자동으로 해결하지만, API를 질의하는 클라이언트는 모호한 해결 오류를 피하기 위해 모듈을 명시적으로 지정해야 합니다.
패키지, 모듈 또는 심볼 정보를 가져오는 엔드포인트의 경우 선택적인 version 쿼리 매개변수를 사용해 원하는 버전을 지정할 수 있습니다. 기본적으로 API는 모듈 또는 패키지의 최신 버전에 대한 정보를 반환합니다. 이 매개변수는 다음을 지원합니다.
?version=v1.2.3 또는 ?version=v0.6.0).master 또는 main을 참조합니다(예: ?version=master). API는 브랜치를 자동으로 해당 의사 버전으로 해석합니다. 사용자 지정 또는 임의의 브랜치 이름은 지원되지 않습니다.version 매개변수를 생략하면 API는 기본적으로 패키지 또는 모듈의 최신 태그 버전을 기준으로 요청을 해석합니다.
특정 패키지에 대한 구조화된 메타데이터를 직접 가져오려면(jq를 사용해 형식 지정):
$ curl https://pkg.go.dev/v1beta/package/github.com/google/go-cmp/cmp | jq .
{
"modulePath": "github.com/google/go-cmp",
"version": "v0.7.0",
"isLatest": true,
"isStandardLibrary": false,
"goos": "all",
"goarch": "all",
"path": "github.com/google/go-cmp/cmp",
"name": "cmp",
"synopsis": "Package cmp determines equality of values.",
"isRedistributable": true
}
특정 브랜치 버전(예: master)을 조회하고 해당 의사 버전으로 자동 해석되는 모습을 보려면:
$ curl -s "https://pkg.go.dev/v1beta/package/github.com/google/go-cmp/cmp?version=master" | jq '{path, version}'
{
"path": "github.com/google/go-cmp/cmp",
"version": "v0.7.1-0.20260310220054-34c9473539b8"
}
우리의 API와 상호작용하는 방법을 보여 주기 위해, 우리는 참조 클라이언트 구현인 pkgsite-cli를 제공합니다. 이 구현은 자체 통합을 구축하려는 개발자들에게 실용적인 예시 역할을 하며, 터미널에서 직접 데이터를 처리하는 방법을 보여 줍니다. API가 계속 진화함에 따라 이 명령의 인터페이스와 동작이 변경될 수 있다는 점에 유의해 주세요.
시작하려면 명령을 설치하세요:
$ go install golang.org/x/pkgsite/cmd/internal/pkgsite-cli@latest
패키지를 검색하려면:
$ pkgsite-cli search "uuid"
github.com/google/uuid
Module: github.com/google/uuid@v1.6.0
Synopsis: Package uuid generates and inspects UUIDs.
... more
특정 패키지를 살펴보려면:
$ pkgsite-cli package github.com/google/go-cmp/cmp
github.com/google/go-cmp/cmp
Name: cmp
Module: github.com/google/go-cmp
Version: v0.7.0 (latest)
Synopsis: Package cmp determines equality of values.
특정 패키지를 import하는 패키지가 무엇인지 보려면:
$ pkgsite-cli package --imported-by github.com/google/go-cmp/cmp
github.com/google/go-cmp/cmp
Name: cmp
Module: github.com/google/go-cmp
Version: v0.7.0 (latest)
Synopsis: Package cmp determines equality of values.
Imported by:
cloud.google.com/go/internal/testutil
cuelang.org/go/internal/cuetxtar
chainguard.dev/apko/pkg/build/types
... more
패키지가 선언한 심볼을 나열하려면:
$ pkgsite-cli package --symbols github.com/google/go-cmp/cmp
github.com/google/go-cmp/cmp
Name: cmp
Module: github.com/google/go-cmp
Version: v0.7.0 (latest)
Synopsis: Package cmp determines equality of values.
Symbols:
type Indirect struct{}
type MapIndex struct{}
type Option interface{}
... more
모듈의 버전을 나열하려면:
$ pkgsite-cli module -versions github.com/google/go-cmp
github.com/google/go-cmp
Version: v0.7.0 (latest)
Repository: https://github.com/google/go-cmp
Has go.mod: yes
Redistributable: yes
Versions:
v0.7.0
v0.6.0
v0.5.9
... more
모듈의 버전과 패키지를 모두 나열하려면:
$ pkgsite-cli module -packages -versions github.com/google/go-cmp
github.com/google/go-cmp
Version: v0.7.0 (latest)
Repository: https://github.com/google/go-cmp
Has go.mod: yes
Redistributable: yes
Versions:
v0.7.0
v0.6.0
v0.5.9
... more
Packages:
github.com/google/go-cmp/cmp Package cmp determines equality of values.
github.com/google/go-cmp/cmp/cmpopts Package cmpopts provides common options for the cmp package.
... more
이 명령은 페이지네이션과 형식 지정을 처리하므로, 스크립트나 수동 조사에 필요한 데이터에 집중할 수 있습니다. 더 자세히 알아보려면 pkgsite-cli’s documentation을 방문하세요.
이상으로 pkg.go.dev API에 대한 짧은 소개를 마칩니다. 시간이 지나면서 인터페이스의 기능을 확장할 계획이지만, 기존 통합이 계속 원활하게 작동하도록 하위 호환성을 유지하는 데 전념하고 있습니다. (pkgsite-cli 참조 클라이언트의 명령줄 인터페이스는 아직 안정적이지 않다는 점에 유의하세요.) issue tracker를 통해 여러분의 피드백을 환영하며, 커뮤니티가 만들어 갈 새로운 도구와 워크플로를 기대합니다.