REST, GraphQL 및 gRPC 자동 스타일 가이드
자바스크립트 사용자는 eslint, PHP 사용자는 PHP Code Sniffer, 루비 사용자는 rubocop이다.이 linter들은 사용자가 유효한 문법을 작성하고 있는지 확인하는 것만은 아니다.그들은 기존의 규칙집을 검사하는데, 때로는 회사에서 작성한 것이다. 예를 들어 거의 사실상의 표준 eslint-airbnb이다.때때로 규칙은 표준 기구(예를 들어 PSR-12)와 PHP-FIG에 의해 제정되며, 이 도구들은 PSR-12 ruleset for CodeSniffer과 같은 일치하는 규칙 집합을 만들 수 있다.
오늘 나는 awesome-lint을 사용해서 awesome-earth이 그들의 규칙에 부합되는 것을 확보해야 했다. 이런 규칙들은 Remark의 가격 인하를 통해 구축된 것이다.
API 설명을 언급할 때, 대부분의 일정 규모를 가진 회사들은 최종적으로 스타일 가이드, 스타일 북, 디자인 가이드 등을 제공한다. 이것은 보통 구글 문서,wiki 또는 다른 유형의 문서/내용 관리 시스템에 있다.나는 이런 책을 많이 보고 많이 썼다.많은 회사 even publish them.
텍스트 기반 스타일 안내서 시간 많이 소모
이러한 텍스트 기반 문서의 문제는 대형, 간결, 무미건조한 문서로 개발자들이 거의 읽지 않는다는 데 있다.만약 개발자가 처음부터 끝까지 읽고 그 중의 모든 내용을 기억한다면, 새로운 규칙을 추가할 때, 이 지식들은 부분적으로 시대에 뒤떨어진다. 왜냐하면 그들은 처음부터 끝까지 읽어야만 이 지식을 이해할 수 있기 때문이다.
API the Docs에서 저는 Salesforce에서 Kelsey Lambert의 강연을 보았습니다. 그들의 스타일 가이드는 예시적인 OpenAPI 설명 문서입니다. 사람들이 어떤 일을 할 때 그들이 사용해야 할 물건의 종류를 알기 위해 수시로 검사를 요구합니다.영업 사원238479347개의 API를 보유한 이 회사의 거두는 API마다 40개의 주요 버전을 유지하는데 그들의 스타일 가이드 실시 방법은 눈과 기억을 끄는 것이다.아, 나는 너희들을 동정한다!나는 이곳에 왔었는데, 기분이 매우 나쁘다.
어떤 개발자도 이 혼란에 대해 책임을 져서는 안 된다.API 개발자들은 바쁘지만, 스타일 가이드를 작성하는 사람들은 개발 과정에서 답을 찾고 싶을 뿐이다.이런 혼란은 업계의 문제이지만 다행히도 이미 일부 도구가 생겨서 자동화를 통해 이런 같은 스타일의 지도 개념을 실시할 수 있다.
구글 api-linter
graphql-doctor x Cap Collectif
graphql-schema-linter
Spectral x Stoplight
HTTP API 스펙트럼
Spectrum은 JSON/YAML 데이터 필터로 OpenAPI v2/v3 및 JSON 모드의 내장 규칙이 있습니다.
일반 문서에서 기본 OpenAPI 규칙 모임을 실행하는 데 많은 조언을 찾았습니다. 이것은 OpenAPI에 익숙하지 않은 개발자에게 도움이 됩니다.
parameter-descriptions을 추가하는 것을 알릴 정도로 작은 것들은 human-readable docs more useful을 만드는 데 도움을 줄 수 있지만, 그들은 심지어 이것이 가능하다는 것을 깨닫지 못할 수도 있다.
Spectrum을 사용하여 rulesets을 만들 수 있습니다. 이 규칙 집합들은 사용자 정의 규칙을 가지고 있을 수도 있고 심지어 사용자 정의 함수를 가지고 있을 수도 있습니다!
이러한 사용자 정의 규칙은 다음과 같이 보일 수 있습니다.
rules:
schema-names-pascal-case:
description: Schema names MUST be written in PascalCase
message: '{{property}} is not PascalCase: {{error}}'
recommended: true
type: style
given: '$.components.schemas.*~'
then:
function: pattern
functionOptions:
match: '^[A-Z][a-zA-Z0-9]*$'
한 걸음 더 나아가겠습니다.
rules:
paths-kebab-case:
description: Should paths be kebab-case.
message: '{{property}} is not kebab-case: {{error}}'
severity: warn
recommended: true
given: $.paths[*]~
then:
function: pattern
functionOptions:
match: "^(\/[a-z0-9-{}]+)+$"
/recent-files은 좋지만 /recent_files은 좋지 않다.너는 이 창의력을 사용하기 시작할 수 있다.
rules:
no-x-headers:
description: "Please do not use headers with X-"
message: "Headers cannot start with X-, so please find a new name for {{property}}. More: https://tools.ietf.org/html/rfc6648"
recommended: true
given: "$..parameters.[?(@.in === 'header')].name"
then:
function: pattern
functionOptions:
notMatch: '^(x|X)-'
X-Foo마리를 초과하더라도 a decade of it causing issues마리를 추가하라고 건의할 것이다.좋아, 우리는 이 규칙으로 그들을 이곳을 떠나게 할 수 있어.가능한 한 빨리 완성하면 개발 과정에서 실제 API가 형성될 것이다.만약 네가 먼저 코드를 만든 후에 확정한다면, 너는 반드시 돌아가서 한 무더기의 코드를 변경해야 한다.지금
/recent_files /recent_files을 위해 일련의 방향을 재정비해야 하기 때문에 발송하지 않기를 바랍니다.만약 API design first workflow을 사용한다면, YAML을 처음 얻었을 때, 이 점을 일찌감치 알아차리고 API가 처음부터 구축되었을 것입니다.Spectrum은 CLI/JS 도구이므로 이 스타일 설명서를 사용할 수 있습니다.
여러 가지 방식으로.
나는 Heroku 또는 PayPal에서 양식 안내서를 추출하여 거대한 예시 규칙집으로 바꾸려고 노력하고 있다.적어도 나는 그 중에서 약간의 영감을 얻어 새로운 규칙집을 만들 수 있다. OpenAPI Contrib > Style Guide.이것은 아마도 재미있는 지역 사회 업무일 것이다.
Spectrum에는 GitHub Action과 GitHub Bot이 하나 더 있습니다. 우리는 개선하기 위해 노력하고 있습니다.댓글 범위와 제안이 곧 출시됩니다!😎
GraphQL Doctor와 Schema Linter
GraphQL은 OpenAPI/JSON 모드를 기반으로 하는 것과 같은 키워드를 가진 built-in type system을 가지고 있다.
GraphQL은 관계를 처리하는 방법과 같은 일부 설계 결정을 더욱 쉽게 합니다.GraphQL은 관련 리소스를 중첩/삽입하거나 복합 문서로 모든 컨텐트를 연결하거나 하이퍼링크를 사용하여 관련 데이터에 링크할 필요가 없습니다.그럼에도 불구하고 GraphQL의 기본 결정 외에 많은 불일치가 발생할 수 있습니다.GraphQL 사용자는 lint에 대한 수요에서 벗어나지 못했지만, 다행히도 위대한 linter가 존재한다. GraphQL Schema Linter.
Custom rules도 이를 작성할 수 있으므로 CI에서 스타일 안내서를 자동으로 실행할 수 있습니다.bot이나 GitHub 작업은 보이지 않지만 조합하기 어렵지 않습니다.
GraphQL 중 하나의 모드 도구는 GraphQL Doctor입니다. 아주 좋은bot이 있습니다.일반적으로 더 많은 linting을 처리하는 데 도움을 주고 싶은 것 같지만, 지금까지는 파괴적인 변화를 검출하는 데 중점을 두고 있다.어떤 유형의 시스템과 마찬가지로 careful evolution과 무모하게 물건을 바꾸는 데 가는 선이 있는데, GraphQL 의사는 후자를 발견할 수 있다.
이 두 도구가 합쳐지는 것을 보면 좋거나 GraphQL 닥터 로봇이 GraphQL 모드 Linter를 지원하기 위해 베이킹을 할 수 있지만 현재는 양역 서비스다.
구글의 "API Linter"
구글은 API 분야에서 매우 재미있는 일을 하고 있다.그들은 API 분야에서 가장 먼저 큰 유저 중 하나로'REST가 필요할 때도 있고 RPC가 필요할 때도 있다'고 설명해 왔다. 그들은 gRPC and HTTP-in-general too에 적용되는 일반적인 도구를 사용해 왔다.API linter는 protobuf 계층에서 실행되지만 HTTP 노드와 함께 작동하도록 설정할 수 있습니다.
When using protocol buffers, each RPC must define the HTTP method and path using the google.api.http annotation:
rpc CreateBook(CreateBookRequest) returns (Book) {
option (google.api.http) = {
post: "/v1/{parent=publishers/*}/books/*"
body: "book"
};
}
message CreateBookRequest {
// The publisher who will publish this book.
// When using HTTP/JSON, this field is automatically populated based
// on the URI, because of the `{parent=publishers/*}` syntax.
string parent = 1;
// The book to create.
// When using HTTP/JSON, this field is populated based on the HTTP body,
// because of the `body: "book"` syntax.
Book book = 2;
// The user-specified ID for the book.
// When using HTTP/JSON, this field is populated based on a query string
// argument, such as `?book_id=foo`. This is the fallback for fields that
// are not included in either the URI or the body.
string book_id = 3;
}
구글은 아니오.
이들은 프로토2에서 프로토3로 팀을 설득하기로 했다.
통치사상
너는 거의 이 물건들로 모든 것을 자동화할 수 있다. 나는 줄곧 많은 생각을 하고 있다
강제 이름이나 복수를 초과하는 일반적인 용례의 규칙입니다.
안전
application/vnd.api+json(JSON:API)을 지원해야 합니다. 단순한 기존 JSON 잘못
버전 제어
총결산
만약 당신이 API 관리라는 용어를 들어 본 적이 있다면, 이것은 바로 대다수 사람들이 이야기하는 것이다.현재 많은 관리를 시도하는 사람들이 모든 PR의 API 설명을 주목하고 그들이 제시한 모든 품질 규칙을 기억하도록 훈련하고 있다.
수동 API 교육은 힘들고 비위에 맞지 않으며 효율이 낮고 끝이 없는 임무로 편집기,git 갈고리,CI 파이프,GitHub 조작이나 로봇의 가는 밧줄로 대체할 수 있다(또는 철저하게 간소화).
고객의 시간을 낭비하지 말고, 그들로 하여금 너의 모순점을 찾아내도록 강요해라.모든 API 개발자가 메모리 스타일 가이드를 배우는 데 시간을 낭비하지 마세요.API 관리 팀이 API를 수동으로 검토하는 시간을 낭비하지 마십시오.앞으로 모든 사람의 시간을 낭비하여 생산 중의 모순을 해결하지 마라.
Reference
이 문제에 관하여(REST, GraphQL 및 gRPC 자동 스타일 가이드), 우리는 이곳에서 더 많은 자료를 발견하고 링크를 클릭하여 보았다 https://dev.to/philsturgeon/automated-style-guides-for-rest-graphql-and-grpc-3ci0텍스트를 자유롭게 공유하거나 복사할 수 있습니다.하지만 이 문서의 URL은 참조 URL로 남겨 두십시오.
우수한 개발자 콘텐츠 발견에 전념
(Collection and Share based on the CC Protocol.)
좋은 웹페이지 즐겨찾기
