NixOS 模块系统：options 声明与模块合并语义

# 形态一：属性集模块（没有参数）
{
  services.nginx.enable = true;
}

# 形态二：函数模块（接收 config/pkgs/lib/options 等）
{ config, pkgs, lib, ... }:
{
  services.nginx.enable = true;
  environment.systemPackages = [ pkgs.curl ];
}

{ lib, ... }:
{
  options.my-service = {
    enable = lib.mkOption {
      type = lib.types.bool;
      default = false;
      description = "是否启用 my-service。";
    };

    port = lib.mkOption {
      type = lib.types.port;
      default = 8080;
      description = "监听端口。";
    };

    backendHosts = lib.mkOption {
      type = lib.types.listOf lib.types.str;
      default = [ "localhost" ];
      description = "上游后端地址列表。";
    };
  };
}

options.web = {
  virtualHosts = lib.mkOption {
    type = lib.types.attrsOf (lib.types.submodule {
      options = {
        serverName = lib.mkOption { type = lib.types.str; };
        ssl = lib.mkOption { type = lib.types.bool; default = false; };
        locations = lib.mkOption {
          type = lib.types.attrsOf (lib.types.submodule {
            options.proxyPass = lib.mkOption { type = lib.types.str; };
          });
        };
      };
    });
    default = {};
  };
};

{ lib, ... }: {
  services.nginx.virtualHosts."example.com" = lib.mkForce {
    listen = [ { addr = "0.0.0.0"; port = 443; ssl = true; } ];
    locations."/api".proxyPass = "http://backend:3000";
  };
}

# 模块 A
{ services.foo.port = 100; }
# 模块 B（同优先级，后加载）
{ services.foo.port = 200; }
# 最终值：200（B 覆盖 A）

# 模块 A
{ services.foo.servers = [ "a" ]; }
# 模块 B
{ services.foo.servers = [ "b" ]; }
# 最终：["a" "b"] 或 ["b" "a"]，取决于 mkOrder / 加载顺序

# 用 mkBefore / mkAfter 控制顺序
{ services.foo.servers = lib.mkBefore [ "primary" ]; }
{ services.foo.servers = lib.mkAfter  [ "backup" ]; }

# 模块 A
{ services.foo.hosts.beta = "127.0.0.1"; }
# 模块 B
{ services.foo.hosts.prod = "10.0.0.5"; }
# 最终：{ beta = ...; prod = ...; }  —— 两个 key 都在

{ config, pkgs, lib, ... }:
{
  config = lib.mkIf config.my-service.enable {
    # 仅当 enable = true 时这些配置生效
    environment.systemPackages = [ pkgs.my-service ];
    systemd.services.my-service = {
      wantedBy = [ "multi-user.target" ];
      serviceConfig.ExecStart = "${pkgs.my-service}/bin/my-service";
    };
  };
}

# 合法：config 尚未完全求值时也可以作为条件
{ config, lib, ... }: {
  config = lib.mkIf (config.services.nginx.enable) {
    networking.firewall.allowedTCPPorts = [ 80 443 ];
  };
}

{ config, lib, ... }: {
  config = lib.mkMerge [
    (lib.mkIf config.isServer {
      services.openssh.enable = true;
    })
    (lib.mkIf config.isDesktop {
      services.xserver.enable = true;
    })
    # 无条件的基础配置
    {
      environment.systemPackages = [ pkgs.vim ];
    }
  ];
}

# modules/my-service.nix
{ config, pkgs, lib, ... }:

let
  cfg = config.my-service;
  # 类型名冲突时引入别名的惯用写法
  types = lib.types;
in
{
  options.my-service = {
    enable = lib.mkOption {
      type = types.bool;
      default = false;
      description = "启用 my-service 守护进程。";
    };

    port = lib.mkOption {
      type = types.port;
      default = 8080;
    };

    dataDir = lib.mkOption {
      type = types.path;
      default = "/var/lib/my-service";
    };

    settings = lib.mkOption {
      type = types.attrsOf types.str;
      default = {};
      description = "任意键值配置，写入 /etc/my-service/settings.conf。";
    };
  };

  config = lib.mkIf cfg.enable {
    # 生成配置文件（内容寻址，纯声明）
    environment.etc."my-service/settings.conf".text =
      lib.generators.toINI {} cfg.settings;

    # 用户与数据目录
    users.users.my-service = {
      isSystemUser = true;
      home = cfg.dataDir;
      createHome = true;
      group = "my-service";
    };
    users.groups.my-service = {};

    # systemd 服务
    systemd.services.my-service = {
      description = "My Service daemon";
      wantedBy = [ "multi-user.target" ];
      after = [ "network.target" ];
      serviceConfig = {
        ExecStart = "${pkgs.my-service}/bin/my-service --config ${config.environment.etc."my-service/settings.conf".source}";
        Restart = "on-failure";
        RestartSec = "2s";
        User = "my-service";
        Group = "my-service";
        WorkingDirectory = cfg.dataDir;
      };
    };

    # 开放防火墙端口（由用户模块再决定是否强制）
    networking.firewall.allowedTCPPorts = lib.mkDefault [ cfg.port ];
  };
}

# configuration.nix 或 flake 模块列表
{ ... }: {
  imports = [
    ./modules/my-service.nix
    # 也可以从 flake 引用外部模块
    # (import ./modules/other.nix)
  ];

  my-service = {
    enable = true;
    port = 8443;
    settings = {
      logLevel = "debug";
      maxConnections = "1000";
    };
  };
}

# flake.nix
{
  outputs = { self, nixpkgs, ... }:
  let
    lib = nixpkgs.lib;
  in {
    nixosModules.my-service = import ./modules/my-service.nix;
    nixosModules.default = self.nixosModules.my-service;

    nixosConfigurations.server = lib.nixosSystem {
      system = "x86_64-linux";
      modules = [
        self.nixosModules.my-service
        ./hosts/server.nix
      ];
    };
  };
}

# 错误
{ config, lib, ... }: {
  services.xserver.enable = lib.mkIf config.myflag.enable true;
}

# 正确
{ config, lib, ... }: {
  config = lib.mkIf config.myflag.enable {
    services.xserver.enable = true;
  };
}

# 导出合并后的完整配置
nixos-rebuild build --show-trace
# 或
nix-instantiate --eval --json '<nixpkgs/nixos>' -A config.my-service --arg configuration ./configuration.nix

# 查看 option 文档（带类型与描述）
nixos-rebuild build --show-trace 2>&1 | grep -A2 'error:'

# 用 trace 查看 option 来源
{ config, lib, ... }: {
  config = lib.traceSeq config.services.foo 0;
  # 或直接声明时带上优先级：
  services.foo.port = lib.mkForce 9090;
}