Contents

Customizing static analysis

静态分析使您可以在执行单行代码之前发现问题. 这是一个功能强大的工具,可用于防止错误并确保代码符合样式准则.

在分析仪的帮助下,您可以找到简单的错字. 例如,也许一个偶然的分号进入了if语句:

void increment() {
  if (count < 10) ;
  count++;
}
lint • Avoid empty statements • example.dart:11 • empty_statements

分析仪还可以帮助您发现更多的细微问题. 例如,也许您忘记了关闭接收器方法:

var _controller = StreamController<String>();
lint • Close instances of `dart.core.Sink` • example.dart:11 • close_sinks

在Dart生态系统中,Dart Analysis Server和其他工具使用分析器包执行静态分析.

您可以自定义静态分析以查找各种潜在问题,包括Dart语言规范中指定的错误和警告. 您还可以配置分析器的插件之一linter,以确保您的代码符合《 Dart样式指南》和《 有效Dart 》中其他建议的指南. Dart工具(例如Dart开发编译器(dartdevc), dartanalyzer flutter analyzeJetBrains IDE)使用分析器包来评估您的代码.

本文档说明了如何使用分析选项文件或Dart源代码中的注释来自定义分析器的行为. 如果要向工具中添加静态分析,请参阅分析器软件包文档和Analysis Server API规范.

The analysis options file

将分析选项文件analysis_options.yaml放置在包的根目录中,与pubspec文件位于同一目录中.

这是一个样本分析选项文件:

include: package:pedantic/analysis_options.1.8.0.yaml

analyzer:
  exclude: [build/**]
  strong-mode:
    implicit-casts: false

linter:
  rules:
    - camel_case_types

该示例说明了最常见的顶级条目:

您可能会看到的另一个标签是language: :,用于实验性语言功能.

如果分析器在程序包的根目录下找不到分析选项文件,则它会走到目录树中,寻找一个. 如果没有可用文件,则分析仪默认为标准检查.

对于大型项目,请考虑以下目录结构:

project root contains analysis_options.yaml (#1) and 3 packages, one of which (my_package) contains an analysis_options.yaml file (#2).

分析器使用文件#1分析my_other_packagemy_other_other_package的代码,并使用文件#2分析my_package的代码.

Enabling stricter type checks

如果您想要比Dart类型系统所需的严格的静态检查,请考虑使用implicit-castsimplicit-dynamic标志:

analyzer:
  strong-mode:
    implicit-casts: false
    implicit-dynamic: false

您可以一起使用标志,也可以单独使用标志. 两者都默认为true .

implicit-casts: <bool>
值为false可以确保类型推断引擎永远不会隐式转换为更特定的类型. 以下有效的Dart代码包含此标志将捕获的隐式下降:
Object o = ...
String s = o; // Implicit downcast
String s2 = s.substring(1);
error • A value of type 'Object' can't be assigned to a variable of type 'String' • invalid_assignment
implicit-dynamic: <bool>
值为false可以确保类型推断引擎在无法确定静态类型时永远不会选择dynamic类型.

Enabling and disabling linter rules

分析器程序包还提供了代码lint. 有各种各样的短绒规则 . 短绒通常是非宗派的—规则不必彼此一致. 例如,某些规则更适合于库程序包,而另一些则是针对Flutter应用程序而设计的. 请注意,与静态分析不同,短绒规则可能具有误报.

Enabling default Google rules: pedantic

要启用Google在其自己的Dart代码中使用的林特规则的列表,请依赖于pedantic软件包,并包括其analysis_options.yaml文件. 除非您需要使用pedantic API,否则请在pubspec.yaml文件中声明对pedantic的开发依赖pubspec.yaml

dev_dependencies:
  pedantic: ^1.0.0

运行pub get ,然后将以下行添加到您的analysis_options.yaml文件中:

include: package:pedantic/analysis_options.yaml

Enabling Effective Dart rules: effective_dart

要启用与有效Dart中的准则相对应的linter规则,请对Effective_dart 添加dev依赖项

dev_dependencies:
  effective_dart: ^1.0.0

运行pub get ,然后将以下行添加到您的analysis_options.yaml文件中:

include: package:effective_dart/analysis_options.yaml

Enabling individual rules

要启用单个linter规则,请将linter:添加到分析选项文件中,然后添加rules: . 在随后的行中,指定要应用的规则,并在其前面加上破折号. 例如:

linter:
  rules:
    - annotate_overrides
    - await_only_futures
    - camel_case_types
    - cancel_subscriptions
    - close_sinks
    - comment_references
    - constant_identifier_names
    - control_flow_in_finally
    - empty_statements

Disabling individual rules

如果您在pedantic包括一个分析选项文件,则可能要禁用其中一些规则. 禁用单个规则与启用它们相似,但有两个区别:

  • 省略规则名称前的破折号( - ).
  • 添加: false规则名称: false .

这是一个分析选项文件的示例,该文件使用所有avoid_shadowing_type_parameters规则,除了avoid_shadowing_type_parameters之外. 它还启用了绒毛await_only_futures

include: package:pedantic/analysis_options.yaml

linter:
  rules:
    avoid_shadowing_type_parameters: false
    await_only_futures: true

Excluding code from analysis

有时,某些代码通过分析失败是可以的. 例如,您可能依赖于您不拥有的程序包生成的代码-生成的代码可以工作,但是在静态分析期间会产生错误. 否则,短绒规则可能会导致您想抑制的误报.

您有几种方法可以将代码从分析中排除:

  • 从分析中排除整个文件.
  • 停止将特定规则应用于单个文件.
  • Stop specific rules from being applied to individual lines of code.
  • 忽略特定规则或错误.

You can also change the severity of rules.

Excluding files

要从静态分析中排除文件,请使用exclude:分析器选项. 您可以列出单个文件,或使用glob语法:

analyzer:
  exclude:
    - lib/client.dart
    - lib/server/*.g.dart
    - test/_data/**

Suppressing rules for a file

要忽略特定文件的特定规则,请在文件中添加ignore_for_file注释:

// ignore_for_file: unused_import

这在注释之前或之后对整个文件起作用,对于生成的代码特别有用.

要取消多个规则,请使用逗号分隔的列表:

// ignore_for_file: unused_import, unused_local_variable, omit_local_variable_types

Suppressing rules for a line of code

要在特定代码行中取消特定规则,请在该代码行上方放置一个ignore注释. 这是一个忽略导致运行时错误的代码的示例,就像您在语言测试中所做的那样:

// ignore: invalid_assignment
int x = '';

要取消多个规则,请提供以逗号分隔的列表:

// ignore: invalid_assignment, const_initialized_with_non_constant_value
const x = y;

或者,将忽略规则附加到它适用的行:

int x = ''; // ignore: invalid_assignment

Customizing analysis rules

每个分析器错误代码linter规则都有默认的严重性. 您可以使用分析选项文件来更改单个规则的严重性,或始终忽略某些规则.

分析仪支持三种严重性级别:

info
不会导致分析失败的参考消息. 示例: todo
warning
除非将分析仪配置为将警告视为错误,否则不会导致分析失败的警告. 示例: analysis_option_deprecated
error
导致分析失败的错误. 示例: invalid_assignment

Ignoring rules

您可以使用errors:字段忽略特定的分析器错误代码linter规则 . 列出规则,其后是: ignore . 例如,以下分析选项文件指示分析工具忽略TODO规则:

analyzer:
  errors:
    todo: ignore

Changing the severity of rules

您可以全局更改特定规则的严重性. 此技术适用于常规分析问题以及棉绒. 例如,以下分析选项文件指示分析工具将无效的分配视为警告,将缺少的返回视为错误,并提供有关无效代码的信息(但不提供警告或错误):

analyzer:
  errors:
    invalid_assignment: warning
    missing_return: error
    dead_code: info

Resources

使用以下资源来了解有关Dart中静态分析的更多信息:

by  ICOPY.SITE