提供在編譯期間處理模組的函式。

它允許開發人員動態新增、刪除和註冊屬性、附加文件等。

在編譯模組後，使用此模組中的許多函式會引發錯誤，因為它們超出檢查執行時間資料的範圍。大多數執行時間資料可透過附加到每個編譯模組的 __info__/1 函式進行檢查。

模組屬性

每個模組都可以裝飾一個或多個屬性。Elixir 目前定義以下屬性

@after_compile

在當前模組編譯後立即呼叫的掛鉤。接受模組或 {module, function_name}。請參閱下方的「編譯回呼」區段。

@after_verify (自 v1.14.0 起)

在當前模組驗證未定義函式、不建議使用等問題後立即呼叫的掛鉤。接受模組或 {module, function_name}。請參閱下方的「編譯回呼」區段。

@before_compile

在編譯模組前呼叫的掛鉤。接受模組或 {module, function_or_macro_name} 元組。請參閱下方的「編譯回呼」區段。

@behaviour

請注意英國拼寫法！

模組可以參照行為，以確保它們實作由 @callback 定義的特定函式簽章。

例如，你可以指定 URI.Parser 行為如下

defmodule URI.Parser do
  @doc "Defines a default port"
  @callback default_port() :: integer

  @doc "Parses the given URL"
  @callback parse(uri_info :: URI.t()) :: URI.t()
end

然後模組可以將其用作

defmodule URI.HTTP do
  @behaviour URI.Parser
  def default_port(), do: 80
  def parse(info), do: info
end

如果行為變更或 URI.HTTP 未實作其中一個回呼，系統會提出警告。

如需詳細文件，請參閱 行為類型規格文件。

@impl (自 v1.5.0 起)

為了協助正確實作行為，你可以選擇為行為的實作回呼宣告 @impl。這會讓回呼明確化，並能協助你找出程式碼中的錯誤。編譯器會在以下情況中提出警告

• 如果你在函式不是回呼時標記 @impl。

• 如果你在其他函式標記 @impl 時，沒有在函式上標記 @impl。如果你在一個函式上標記 @impl，你必須將該行為的其他所有回呼標記為 @impl。

@impl 以每個內容為基礎運作。如果你透過巨集產生函式並標記 @impl，這不會影響產生該函式的模組。

@impl 透過讓其他開發人員清楚函式正在實作回呼，也有助於維護性。

使用 @impl，上述範例可以改寫為

defmodule URI.HTTP do
  @behaviour URI.Parser

  @impl true
  def default_port(), do: 80

  @impl true
  def parse(info), do: info
end

你可以將 false、true 或特定行為傳遞給 @impl。

defmodule Foo do
  @behaviour Bar
  @behaviour Baz

  # Will warn if neither Bar nor Baz specify a callback named bar/0.
  @impl true
  def bar(), do: :ok

  # Will warn if Baz does not specify a callback named baz/0.
  @impl Baz
  def baz(), do: :ok
end

程式碼現在更具可讀性，因為現在清楚哪些函式是 API 的一部分，哪些是回呼實作。為了加強這個概念，@impl true 會自動將函式標記為 @doc false，除非明確設定 @doc，否則會停用文件。

@compile

定義模組編譯的選項。這用於設定 Elixir 和 Erlang 編譯器，以及外部工具新增的任何其他編譯傳遞。例如

defmodule MyModule do
  @compile {:inline, my_fun: 1}

  def my_fun(arg) do
    to_string(arg)
  end
end

多次使用 @compile 會累積，而不是覆寫先前的使用。請參閱下方的「編譯選項」區段。

@deprecated（自 v1.6.0 起）

提供函式的棄用原因。例如

defmodule Keyword do
  @deprecated "Use Kernel.length/1 instead"
  def size(keyword) do
    length(keyword)
  end
end

Mix 編譯器會自動尋找呼叫已棄用的模組，並在編譯期間發出警告。

使用 @deprecated 屬性也會反映在給定函式和巨集的說明文件中。您可以在 @deprecated 屬性和說明文件元資料之間進行選擇，以提供硬棄用（帶有警告）和軟棄用（不帶警告）

這是一個軟棄用，因為它只是將說明文件註解為已棄用

@doc deprecated: "Use Kernel.length/1 instead"
def size(keyword)

這是一個硬棄用，因為它會發出警告並將說明文件註解為已棄用

@deprecated "Use Kernel.length/1 instead"
def size(keyword)

目前 @deprecated 僅支援函式和巨集。但是，您可以在註解元資料中使用 :deprecated 鍵來註解模組、類型和回呼的說明文件。

我們建議謹慎使用此功能，尤其是函式庫作者。棄用程式碼總是會將負擔推向函式庫使用者。我們還建議在棄用後長時間維護已棄用的功能，讓開發人員有充裕的時間進行更新（除非在某些情況下，例如存在安全性問題時，不希望保留已棄用的 API）。

@doc 和 @typedoc

提供後接屬性的實體文件。 @doc 用於函式、巨集、回呼或巨集回呼，而 @typedoc 用於類型（公開或不透明）。

接受其中之一

• 字串（通常是 heredoc）
• false，這將使實體對 ExDoc 等文件提取工具不可見
• 關鍵字清單，自 Elixir 1.7.0 起

例如

defmodule MyModule do
  @typedoc "This type"
  @typedoc since: "1.1.0"
  @type t :: term

  @doc "Hello world"
  @doc since: "1.1.0"
  def hello do
    "world"
  end

  @doc """
  Sums `a` to `b`.
  """
  def sum(a, b) do
    a + b
  end
end

如上例所示，自 Elixir 1.7.0 起，@doc 和 @typedoc 也接受關鍵字清單，作為提供有關實體的任意元資料的方法。 ExDoc 和 IEx 等工具可以使用此資訊顯示註解。常見的用例是 :since 鍵，可用於註解函式引入的版本。

如範例所示，可以在實體之前多次使用這些屬性。但是，如果使用二進位檔兩次，編譯器會發出警告，因為這會取代前一次使用的文件文字。使用關鍵字清單多次使用會將清單合併為一個。

請注意，由於編譯器也定義了一些額外的元資料，因此有一些保留的鍵會被忽略，如果使用的話會發出警告。目前這些是：:opaque 和 :defaults。

一旦編譯這個模組，這些資訊就會透過 Code.fetch_docs/1 函數取得。

@dialyzer

定義在使用 :dialyzer 時請求或抑制的警告。

接受原子、元組或原子和元組的清單。例如

defmodule MyModule do
  @dialyzer {:nowarn_function, [my_fun: 1]}

  def my_fun(arg) do
    M.not_a_function(arg)
  end
end

有關支援的警告清單，請參閱 :dialyzer 模組。

重複使用 @dialyzer 會累積，而不是覆寫先前的使用。

@external_resource

指定當前模組的外部資源。

有時模組會內嵌來自外部檔案的資訊。這個屬性允許模組註解已使用的外部資源。

工具可以使用這些資訊來確保在任何外部資源變更時重新編譯模組，例如：mix compile.elixir。

指定的檔案路徑被解釋為相對於包含專案的 mix.exs 的資料夾，也就是目前的作業目錄，而不是宣告 @external_resource 的檔案。

如果外部資源不存在，模組仍然依賴於它，導致在新增檔案後重新編譯模組。

@file

變更屬性後函數或巨集在堆疊追蹤中使用的檔名，例如

defmodule MyModule do
  @doc "Hello world"
  @file "hello.ex"
  def hello do
    "world"
  end
end

請注意，這僅適用於來自定義內部範圍（包括其模式和防護）的例外/診斷。例如

defmodule MyModule do # <---- module definition
  @file "hello.ex"
  defp unused(a) do # <---- function definition
    "world" # <---- function scope
  end

  @file "bye.ex"
  def unused(_), do: true
end

如果您執行此程式碼，並將第二個「未使用的」定義註解掉，您會看到 hello.ex 在報告警告時會被用作堆疊追蹤，但如果您取消註解，您會看到錯誤不會提到 bye.ex，因為它是一個模組層級錯誤，而不是表達式層級錯誤。

@moduledoc

提供目前模組的說明文件。

defmodule MyModule do
  @moduledoc """
  A very useful module.
  """
  @moduledoc authors: ["Alice", "Bob"]
end

接受字串（通常是 heredoc）或 false，其中 @moduledoc false 會讓模組對文件提取工具（例如 ExDoc）不可見。

與 @doc 類似，也接受關鍵字清單來提供模組的元資料。有關更多詳細資訊，請參閱上方 @doc 的說明文件。

一旦編譯這個模組，這些資訊就會透過 Code.fetch_docs/1 函數取得。

@nifs（自 v1.16.0 起）

將被原生實作（NIF）覆寫的函式清單及其元數。

defmodule MyLibrary.MyModule do
  @nifs [foo: 1, bar: 2]

  def foo(arg1), do: :erlang.nif_error(:not_loaded)
  def bar(arg1, arg2), do: :erlang.nif_error(:not_loaded)
end

有關更多資訊，請參閱 Erlang 說明文件：https://erlang.dev.org.tw/doc/man/erl_nif

@on_definition

當目前模組中的每個函式或巨集被定義時，將會呼叫的掛鉤。在註解函式時很有用。

接受模組或 {module, function_name} 組合。函式必須採用 6 個參數

• 模組環境
• 函式/巨集的種類：:def、:defp、:defmacro 或 :defmacrop
• 函式/巨集名稱
• 引用的參數清單
• 引用的防護清單
• 引用的函式主體

如果要定義的函式/巨集有多個子句，則會針對每個子句呼叫掛鉤。

與其他掛鉤不同，@on_definition 只會呼叫函式，而不會呼叫巨集。這是為了避免 @on_definition 回呼重新定義剛剛定義的函式，而採用更明確的方法。

當只提供模組時，函式假設為 __on_definition__/6。

範例

defmodule Hooks do
  def on_def(_env, kind, name, args, guards, body) do
    IO.puts("Defining #{kind} named #{name} with args:")
    IO.inspect(args)
    IO.puts("and guards")
    IO.inspect(guards)
    IO.puts("and body")
    IO.puts(Macro.to_string(body))
  end
end

defmodule MyModule do
  @on_definition {Hooks, :on_def}

  def hello(arg) when is_binary(arg) or is_list(arg) do
    "Hello" <> to_string(arg)
  end

  def hello(_) do
    :ok
  end
end

@on_load

只要載入模組，就會呼叫的掛鉤。

接受當前模組中函數的函數名稱（作為原子）。該函數必須具有 0 元性（無參數）。如果函數未傳回 :ok，則模組的載入將會中止。例如

defmodule MyModule do
  @on_load :load_check

  def load_check do
    if some_condition() do
      :ok
    else
      :abort
    end
  end

  def some_condition do
    false
  end
end

@vsn

指定模組版本。接受任何有效的 Elixir 值，例如

defmodule MyModule do
  @vsn "1.0"
end

結構屬性

• @derive - 為當前模組中定義的結構衍生給定協定的實作

• @enforce_keys - 確保在建立當前模組中定義的結構時，總是設定給定的金鑰

請參閱 defstruct/1 以取得有關建立和使用結構的更多資訊。

類型規格屬性

下列屬性是類型規格的一部分，且也內建於 Elixir 中

• @type - 定義要在 @spec 中使用的類型
• @typep - 定義要在 @spec 中使用的私人類型
• @opaque - 定義要在 @spec 中使用的不透明類型
• @spec - 提供函數的規格
• @callback - 提供行為回呼的規格
• @macrocallback - 提供巨集行為回呼的規格
• @optional_callbacks - 指定哪些行為回呼和巨集行為回呼是選用的
• @impl - 宣告回呼函數或巨集的實作

如需詳細文件，請參閱 類型規格文件。

自訂屬性

除了上述內建屬性之外，也可以新增自訂屬性。自訂屬性使用 @/1 算子，後接有效的變數名稱來表示。提供給自訂屬性的值必須是有效的 Elixir 值

defmodule MyModule do
  @custom_attr [some: "stuff"]
end

如需在定義自訂屬性時可用的更進階選項，請參閱 register_attribute/3。

編譯回呼

有三個編譯回呼，依序呼叫：@before_compile、@after_compile 和 @after_verify。它們的說明如下。

@before_compile

在編譯模組之前會呼叫的掛勾。這通常用於變更當前模組的編譯方式。

接受模組或 {module, function_or_macro_name} 元組。函式/巨集必須帶有一個參數：模組環境。如果它是巨集，其傳回值將在編譯開始前注入到模組定義的結尾。

當僅提供模組時，函式/巨集假設為 __before_compile__/1。

呼叫回會按其註冊順序執行。任何可覆寫的定義將在第一個呼叫回執行前具體化。定義可以在另一個編譯前呼叫回中再次變為可覆寫，並在所有呼叫回執行後最後一次具體化。

注意：呼叫回函式/巨集必須置於獨立模組中（因為呼叫呼叫回時，目前模組尚未存在）。

範例

defmodule A do
  defmacro __before_compile__(_env) do
    quote do
      def hello, do: "world"
    end
  end
end

defmodule B do
  @before_compile A
end

B.hello()
#=> "world"

@after_compile

在當前模組編譯後立即呼叫的掛鉤。

接受模組或 {module, function_name} 元組。函式必須帶有兩個參數：模組環境及其位元組碼。當僅提供模組時，函式假設為 __after_compile__/2。

呼叫回會按其註冊順序執行。

Module 函式預期尚未編譯的模組（例如 definitions_in/1）在呼叫 @after_compile 時仍可用。

範例

defmodule MyModule do
  @after_compile __MODULE__

  def __after_compile__(env, _bytecode) do
    IO.inspect(env)
  end
end

@after_verify

在當前模組針對未定義函式、不建議使用等進行驗證後立即呼叫的掛鉤。模組在編譯後總是會驗證。在 Mix 專案中，當任何執行時期依賴項變更時，模組也會驗證。因此，這對於在避免編譯時期依賴項的同時執行當前模組的驗證很有用。

接受一個模組或一個 {module, function_name} 元組。函式必須帶一個參數：模組名稱。當只提供一個模組時，函式假設為 __after_verify__/1。

呼叫回會按其註冊順序執行。

Module 函式預期尚未編譯的模組在呼叫 @after_verify 時不再可用。

範例

defmodule MyModule do
  @after_verify __MODULE__

  def __after_verify__(module) do
    IO.inspect(module)
    :ok
  end
end

編譯選項

@compile 屬性接受不同的選項，這些選項由 Elixir 和 Erlang 編譯器使用。以下文件記錄了一些常見的用例

• @compile :debug_info - 包含 :debug_info，無論 Code.get_compiler_option/1 中對應的設定為何

• @compile {:debug_info, false} - 停用 :debug_info，無論 Code.get_compiler_option/1 中對應的設定為何。請注意，不建議停用 :debug_info，因為這會移除 Elixir 編譯器和其他工具靜態分析程式碼的能力。如果您想在部署時移除 :debug_info，像 mix release 這樣的工具預設就會這麼做。

• @compile {:inline, some_fun: 2, other_fun: 3} - 內聯給定的名稱/元組對。內聯會在區域內套用，來自其他模組的呼叫不會受到此選項影響

• @compile {:autoload, false} - 停用編譯後自動載入模組。相反地，模組會在傳送給它之後載入

• @compile {:no_warn_undefined, Mod} 或 @compile {:no_warn_undefined, {Mod, fun, arity}} - 如果給定的模組或給定的 Mod.fun/arity 未定義，則不會發出警告