type_annotate_public_apis 진단: 공개 API에는 타입을 명시해요

type_annotate_public_apis는 공개 API의 매개변수 타입과 반환 타입에 타입 애너테이션을 붙이도록 안내하는 린트(lint) 규칙이에요. 타입 애너테이션은 라이브러리를 어떻게 사용해야 하는지 알려주는 중요한 문서 역할을 해요.

출처: type_annotate_public_apis

본문

설명

Effective Dart에서 안내하듯, 공개 API에는 타입 애너테이션을 붙이는 걸 선호해요 (PREFER). 타입 애너테이션은 라이브러리를 어떻게 써야 하는지를 알려주는 중요한 문서예요. 공개 메서드와 함수의 매개변수 타입과 반환 타입을 명시하면, 사용자들이 API가 무엇을 기대하고 무엇을 제공하는지 이해하기 쉬워져요.

공개 API가 받는 값의 범위를 Dart의 타입 시스템으로 표현할 수 없다면 타입을 붙이지 않아도 괜찮아요. 그런 경우에는 암시적인 dynamic이 그 API에 맞는 올바른 타입이에요.

라이브러리 내부 코드(비공개이거나 중첩 함수 같은 것)에는 도움이 되는 곳에만 애너테이션을 붙이면 돼요. 반드시 붙여야 한다고 느낄 필요는 없어요.

좋지 않은 코드 (BAD)

install(id, destination) {
  // ...
}

여기서는 id가 뭔지 알 수 없어요. 문자열일까요? 그럼 destination은요? String일까요, File 객체일까요? 그리고 이 메서드는 동기(synchronous)일까요, 비동기(asynchronous)일까요?

좋은 코드 (GOOD)

타입을 붙이면 이 모든 것이 분명해져요.

Future<bool> install(PackageId id, String destination) {
  // ...
}

호환되지 않는 규칙

type_annotate_public_apis 린트는 다음 규칙과 호환되지 않아요.

omit_obvious_property_types

규칙 활성화하기

analysis_options.yaml 파일의 linter > rules 아래에 type_annotate_public_apis를 추가해서 활성화할 수 있어요.

linter:
  rules:
    - type_annotate_public_apis

YAML 맵 문법으로 설정하고 있다면 linter > rules 아래에 type_annotate_public_apis: true를 추가해요.

linter:
  rules:
    type_annotate_public_apis: true

type_annotate_public_apis 진단: 공개 API에는 타입을 명시해요