분석기 플러그인

Analyzer 플러그인을 사용하면 Dart 프로젝트를 위한 커스텀 린트(lint), 경고, IDE 빠른 수정을 만들 수 있어요. 이 페이지에서는 플러그인을 사용하는 방법과 직접 작성하는 방법을 안내해 드릴게요.

출처: Analyzer plugins

본문

버전 참고: 분석기 플러그인 지원은 Dart 3.10에서 추가되었어요.

Analyzer 플러그인은 Dart 분석기(analyzer)를 확장해 커스텀 진단(린트와 경고)을 보고하고, 빠른 수정을 제공하며, 어시스트(assist)를 제공해요. 이 기능은 IDE에서 직접, 그리고 dart analyze이나 flutter analyze를 실행할 때 커맨드라인에서 바로 사용할 수 있어요.

분석기 플러그인 사용하기

패키지 또는 워크스페이스 루트의 analysis_options.yaml 파일에서 활성화하면 Dart 프로젝트에서 분석기 플러그인을 사용할 수 있어요.

pub.dev에서 분석기 플러그인을 검색할 수 있어요.

플러그인 활성화하기

분석기 플러그인을 활성화하려면 analysis_options.yaml 파일의 최상위 plugins 섹션에 추가하세요. 버전 제약을 사용해 pub.dev에서 플러그인을 추가할 수 있어요.

plugins:
  my_plugin: ^1.0.0

플러그인을 로컬에서 개발 중이라면 로컬 경로를 사용할 수도 있어요.

plugins:
  my_plugin:
    path: /path/to/my_plugin

plugins 섹션을 변경한 후에는 Dart Analysis Server를 다시 시작해야 변경 사항이 적용돼요.

진단 구성하기

플러그인은 경고(warning)와 린트(lint) 두 종류의 진단을 보고할 수 있어요. 분석기는 기본적으로 이를 다르게 처리해요.

플러그인이 정의한 경고는 기본적으로 활성화돼요(표준 분석기 경고와 마찬가지로).
플러그인이 정의한 린트 규칙은 기본적으로 비활성화되어 있으며 분석 옵션 파일에서 명시적으로 활성화해야 해요.

특정 린트 규칙은 플러그인의 Diagnostics 섹션 아래에서 활성화하거나 비활성화할 수 있어요.

plugins:
  my_plugin:
    path: /path/to/my_plugin
    diagnostics:
      rule_1: true
      rule_2: true
      rule_3: false

위 예시에서 rule_1과 rule_2는 활성화되고, rule_3은 명시적으로 비활성화돼요. 이는 include: 파일에서 비활성화되었을 수 있는 규칙을 덮어쓰는 데 유용해요.

진단 억제하기

내장 Dart 진단과 같은 ignore 주석을 사용해 플러그인의 진단을 억제할 수 있어요. 특정 플러그인의 진단을 대상으로 하려면 진단 코드 앞에 플러그인 이름과 슬래시(/)를 붙이세요.

예를 들어 some_plugin이라는 플러그인의 some_code 코드를 가진 진단을 억제하려면 다음 형식 중 하나를 사용해요.

단일 줄 억제:

// ignore: some_plugin/some_code

파일 전체 억제:

// ignore_for_file: some_plugin/some_code

분석기 플러그인 작성하기

커스텀 정적 분석, 빠른 수정, 어시스트를 Dart 개발 경험에 추가하려면 나만의 분석기 플러그인을 만드세요.

플러그인 패키지 설정하기

분석기 플러그인은 특정 의존성과 구조를 가진 표준 Dart 패키지예요. 핵심 의존성은 Plugin 클래스를 제공하는 analysis_server_plugin 패키지예요.

pubspec.yaml 파일을 만드세요. 예를 들면:

name: test_analyzer_plugin
version: 0.0.1

environment:
  sdk: ^3.10.0

dependencies:
  analysis_server_plugin: ^0.3.0
  analyzer_plugin: ^0.13.0
  analyzer: ^8.0.0

플러그인 진입점(entry point)을 만드세요. 예를 들면:

import 'package:analysis_server_plugin/plugin.dart';
import 'package:analysis_server_plugin/registry.dart';

final plugin = SimplePlugin();

class SimplePlugin extends Plugin {
  @override
  String get name => 'Simple plugin';

  @override
  void register(PluginRegistry registry) {
    // 진단, 빠른 수정, 어시스트를 등록하세요.
  }
}

위 코드는 플러그인 진입점의 기본 구조를 나타내요. 패키지에 lib/main.dart 파일이 있는지 확인하세요. 분석 서버가 플러그인을 로드할 때 이 파일이 진입점이 되거든요.

핵심 포인트:

클래스를 인스턴스화하는 plugin이라는 최상위 변수가 필요해요. Dart Analysis Server는 이 변수를 찾아요.
클래스는 package:analysis_server_plugin/plugin.dart의 Plugin을 상속해야 해요.
register 메서드를 오버라이드해 플러그인의 기능을 추가하세요. 이 메서드는 커스텀 분석 규칙, 빠른 수정, 어시스트를 분석기에 등록하는 주요 진입점 역할을 해요.

팁: 플러그인을 변경한 후에는 Dart Analysis Server를 다시 시작해야 변경 사항이 적용돼요.

플러그인 기능 구현하기

기본 플러그인 패키지를 준비했다면 register 메서드를 구현해 커스텀 기능을 추가할 수 있어요.

특정 기능을 구현하는 방법은 다음 가이드를 참고하세요.

Writing rules(규칙 작성)
Writing fixes(수정 작성)
Writing assists(어시스트 작성)
Testing rules(규칙 테스트)

규칙, 수정, 어시스트의 많은 예시는 Dart Analysis Server에서 확인할 수 있어요.

Dart Analysis Server의 규칙
Dart Analysis Server의 수정
Dart Analysis Server의 어시스트

플러그인 디버그하기

플러그인이 예상대로 작동하지 않으면 다음 방법을 권장해요.

가장 먼저 analyzer 진단 페이지를 확인하세요. 플러그인의 isolate가 크래시하면 "plugins" 화면에 크래시 정보와 스택 트레이스가 표시돼요.
print 문은 작동하지 않아요. 플러그인은 별도의 isolate에서 실행되며 표준 출력이 콘솔에 연결되지 않기 때문이에요.
플러그인의 실행을 추적하고 값을 검사하는 가장 확실한 방법은 플러그인 코드에서 로그 파일에 작성하는 거예요.

더 알아보기

Customizing static analysis — 분석 옵션 파일로 정적 분석 커스터마이징하기.
pub.dev에서 분석기 플러그인 검색 — 사용 가능한 플러그인 찾기.