Dialyzer 与类型规范：Erlang 静态分析的工程实践

%% 没有 spec 也能分析
add(X, Y) -> X + Y.

%% Dialyzer 推导出的 success typing 大致为：
%% add(number(), number()) -> number()

-module(payment).

%% 单子句 spec
-spec charge(Amount :: pos_integer(), Currency :: atom()) -> {ok, binary()} | {error, term()}.

%% 多子句用分号分隔
-spec parse(binary()) -> {ok, map()} | {error, invalid_format}.

%% 带约束的 spec
-spec split(non_neg_integer(), [T]) -> {[T], [T]} when T :: term().

-module(types).

%% 类型别名
-type user_id() :: pos_integer().
-type email() :: binary().
-type status() :: active | inactive | suspended.

%% 记录类型
-record(user, {
    id    :: user_id(),
    email :: email(),
    tags  :: [atom()]
}).
-type user() :: #user{}.

%% 不透明类型：外部只能整体使用，不能拆解
-opaque handle() :: {ref, reference(), node()}.

%% 导出类型供其他模块引用
-export_type([user_id/0, user/0, handle/0]).

%% 基础
atom(), binary(), bitstring(), boolean(), float(), integer(),
number(), pid(), port(), reference(), tuple(), map(), list(),
nil(), term(), any(), none(), no_return()

%% 参数化
[Type]              % 元素为 Type 的列表
[Type, ...]         % 非空列表
#{key := Type}      % 必含 key 的 map
#{key => Type}      % 可含 key 的 map
fun((A) -> B)       % 函数类型
fun((...) -> B)     % 任意参数
tuple() | {A, B}    % 定长元组

%% 数值区间
1..255
0..16#FF

-type request() :: {get, binary()} | {put, binary(), term()}.
-type reply()   :: {ok, term()} | {error, term()}.

-spec handle_call(request(), gen_server:from(), state()) ->
    {reply, reply(), state()}.

%% rebar.config
{dialyzer, [
    {warnings, [unmatched_returns, error_handling, underspecs]},
    {plt_apps, all_deps},          % PLT 包含所有依赖
    {plt_extra_apps, [cowboy, jsx]},
    {plt_location, local},
    {plt_prefix, "my_service"}
]}.

%% 首次构建（含所有依赖，较慢）
rebar3 dialyzer

%% 依赖变更后重建 PLT
rebar3 dialyzer --update-plt

%% 只分析不重建
rebar3 dialyzer --no_check_plt

# GitHub Actions 缓存 PLT
- uses: actions/cache@v4
  with:
    path: _build/default/rebar3_*_plt
    key: plt-${{ runner.os }}-${{ hashFiles('rebar.lock') }}

%% 错误示范：maps:get 无默认值 + 后续解构必然失败
validate(Config) ->
    Timeout = maps:get(timeout, Config),   % 若 Config 是 list 则必然 badmap
    Timeout * 1000.

%% 修复：加类型守卫或默认值
validate(Config) when is_map(Config) ->
    Timeout = maps:get(timeout, Config, 5000),
    Timeout * 1000.

%% 若确实需要支持字符串金额，改 spec 并加转换
-spec charge(Amount :: pos_integer() | binary(), Currency :: atom()) ->
    {ok, binary()} | {error, term()}.
charge(Amount, Currency) when is_binary(Amount) ->
    charge(binary_to_integer(Amount), Currency);
charge(Amount, Currency) when is_integer(Amount), Amount > 0 ->
    do_charge(Amount, Currency).

%% 告警：返回值被忽略
{ok, _} = application:ensure_all_started(my_app),  % OK，已匹配
file:write_file("/tmp/x", Data),                    % 告警：返回值未处理

%% 修复
case file:write_file("/tmp/x", Data) of
    ok -> continue();
    {error, Reason} -> logger:error("write failed: ~p", [Reason])
end.

%% underspecs：实际只返回 ok | error，spec 写得太宽
-spec save(map()) -> term().        % 太宽
-spec save(map()) -> ok | {error, term()}.   % 准确

%% 抑制单个函数的特定告警
-dialyzer({nowarn_function, legacy_adapter/2}).

%% 抑制特定类型的告警
-dialyzer({nowarn_function, [old_api/1, old_api/2]}).

%% 抑制整模块的某类告警（慎用）
-dialyzer(no_return).

%% 属性测试发现的具体反例，往往能反哺 spec 修正
prop_reverse() ->
    ?FORALL(L, list(integer()),
        lists:reverse(lists:reverse(L)) =:= L).

%% 对应的 spec 应精确表达
-spec reverse([T]) -> [T] when T :: term().

- name: Static Analysis
  run: |
    rebar3 xref
    rebar3 dialyzer

%% rebar.config —— 让告警成为构建失败条件
{dialyzer, [
    {warnings, [unmatched_returns, error_handling, underspecs,
                unknown, race_conditions]},
    {plt_apps, all_deps}
]}.

%% 生成详细报告
rebar3 dialyzer > dialyzer.log 2>&1

%% 按模块聚合告警数量
grep -oP '(?<=^)\w+(?=\.erl)' dialyzer.log | sort | uniq -c | sort -rn