Haskell 模块系统：module 与 import

Haskell 的模块系统是组织代码的核心机制。它能让你把大型程序拆分成多个可管理的文件，明确哪些功能对外可见、哪些内部使用。掌握 module 和 import 关键字，你就能写出结构清晰、易于维护的代码。

理解模块的基本概念

模块（Module）是 Haskell 代码的容器。每个 .hs 文件通常对应一个模块，模块名必须与文件名保持一致（大小写敏感）。例如，Data.List 模块对应的文件就是 Data/List.hs。

掌握模块系统，你将学会：

• 如何定义自己的模块并控制导出内容
• 如何导入他人编写的模块
• 如何避免命名冲突
• 如何组织大型项目结构

定义自己的模块

使用 module 关键字导出全部内容

文件开头的 module 声明定义了模块名及其导出的函数。如果不指定导出列表，模块会导出所有顶级定义。

-- File: MyUtils.hs
module MyUtils where

add :: Int -> Int -> Int
add x y = x + y

multiply :: Int -> Int -> Int
Multiply x y = x * y

double :: Int -> Int
double x = x * 2

这段代码定义了 MyUtils 模块，它向外部导出三个函数：add、multiply 和 double。任何导入这个模块的文件都能使用这三个函数。

使用 export 列表精确控制导出

显式声明导出列表是更好的习惯。它让你明确哪些函数是公开 API，哪些是内部实现。当需要重构内部代码时，只需确保导出的函数签名不变，就不会影响使用者。

module Config (parseConfig, Config(..)) where

data Config = Config
  { host :: String
  , port :: Int
  } deriving (Show)

-- 内部函数，仅在模块内使用
validateHost :: String -> Bool
validateHost s = length s > 0

-- 公开函数
parseConfig :: String -> Config
parseConfig input = Config input 8080

这个示例展示了三种导出方式：第一，parseConfig 导出了一个普通函数；第二，Config(..) 导出类型及其所有值构造器；第三，你也可以写成 Config { host, port } 来仅导出类型和指定字段，但隐藏值构造器。

导出类型但不导出构造器

隐藏数据构造器能有效实现封装。使用者只能通过你提供的函数来创建和操作数据，无法直接绕过你的逻辑。

module BankAccount (BankAccount, createAccount, deposit, withdraw) where

newtype BankAccount = BankAccount (IORef (Int, String))

createAccount :: String -> IO BankAccount
createAccount name = BankAccount <$> newIORef (0, name)

deposit :: BankAccount -> Int -> IO ()
deposit (BankAccount ref) amount = modifyIORef ref $ \(bal, name) -> (bal + amount, name)

withdraw :: BankAccount -> Int -> IO (Maybe Int)
withdraw (BankAccount ref) amount = modifyIORef ref $ \(bal, name) ->
  if bal >= amount then (bal - amount, name) else (bal, name) >>= \r -> Just (fst r)
```

外部代码无法直接创建 `BankAccount` 值，只能通过 `createAccount` 来初始化账户。这种设计保证了账户状态的完整性。

---

## 导入模块的各种方式

### 基本导入语法

`import` 语句让你在当前作用域中使用其他模块导出的定义。导入语句必须放在文件顶部、模块声明之后（如果有的话）。

```haskell
module Main where

import Data.List
import Data.Char

main :: IO ()
main = print (nub "hello world")
```

`nub` 函数来自 `Data.List`，它会移除列表中的重复元素。这段代码输出 `"heowrld"`。

### 指定导入特定函数

导入过多函数会污染命名空间，可能导致命名冲突。使用 `hiding` 或显式列出需要的内容可以让代码更清晰。

```haskell
import Data.List (nub, sort)  -- 只导入这两个函数
import Data.Char hiding (toUpper)  -- 导入所有函数，除了 toUpper
```

第一种写法明确告诉编译器只需要 `nub` 和 `sort`，其他函数不可见。第二种写法是反向选择，`Data.Char` 的所有函数都可使用，但 `toUpper` 被排除在外。

### 使用 as 关键字重命名模块

当你需要使用两个不同模块中同名函数时，或者模块名太长时，可以给模块起别名。

```haskell
import Data.List as List
import Data.Map as Map

-- 现在你可以用 List.nub 和 Map.lookup 来区分它们
```

长模块名起别名特别有用：

```haskell
import Text.Printf as Printf
import System.Environment as Env

main :: IO ()
main = do
  args <- Env.getArgs
  Printf.printf "Received: %s\n" (head args)
```

### 使用 qualified 限定导入

`qualified` 关键字强制你必须使用 `模块名.函数名` 的写法来访问函数。虽然写起来更长，但代码可读性更好，调用来源一目了然。

```haskell
import qualified Data.Map as Map

-- 错误：nub 未定义
-- print (nub [1,2,3])

-- 正确：必须使用 Map. 前缀
print (Map.empty :: Map.Map Int ())
print (Map.singleton 1 "one")
```

这种写法在大型项目中尤为重要。当看到 `Controller.run` 或 `Model.findById` 时，你立刻知道这些函数来自哪个模块。

---

## 模块的组织与层级结构

### 创建多层级的模块

Haskell 使用点号（.）来表示模块层级，这对应文件系统中的目录结构。`Data.List` 模块实际位于 `Data/List.hs`，而 `Data.ByteString.Char8` 对应 `Data/ByteString/Char8.hs`。

创建项目结构时，遵循以下约定：

```
myproject/
├── MyProject/
│   ├── Core.hs
│   ├── API.hs
│   └── Types.hs
├── Main.hs
└── myproject.cabal
```

在 `MyProject/Core.hs` 中定义模块：

```haskell
module MyProject.Core where

-- 核心业务逻辑
```

在 `Main.hs` 中导入：

```haskell
module Main where

import MyProject.Core
import MyProject.API
import MyProject.Types
```

### 正确处理循环依赖

模块之间不能存在循环依赖。如果 A 导入 B，B 导入 A，编译器会报错。解决循环依赖的方法有两种：第一，提取公共代码到第三个模块 C；第二，使用依赖反转，将共享类型定义在独立的模块中。

```haskell
-- ModuleA.hs
module ModuleA (funA) where

import ModuleC  -- 共享依赖

funA :: String -> String
funA = reverse
```

```haskell
-- ModuleB.hs
module ModuleB (funB) where

import ModuleC

funB :: String -> String
funB = length . show
```

```haskell
-- ModuleC.hs
module ModuleC where

-- 共享的类型和辅助函数
type Id = Int
```

---

## 常用标准库模块速查

Haskell 的标准库被组织在多个模块中，以下是开发中最常用的模块及其用途：

| 模块 | 用途 | 核心函数 |
|------|------|----------|
| `Prelude` | 默认导入的基础函数 | `map`, `filter`, `foldr`, `(++)` |
| `Data.List` | 列表操作 | `nub`, `sort`, `group`, `tails` |
| `Data.Map` | 键值映射（字典） | `insert`, `lookup`, `fromList` |
| `Data.Set` | 无序集合 | `insert`, `member`, `union` |
| `Data.Char` | 字符处理 | `isSpace`, `toUpper`, `digitToInt` |
| `Data.Maybe` | Maybe 类型操作 | `fromMaybe`, `catMaybes`, `mapMaybe` |
| `Data.Either` | Either 类型操作 | `lefts`, `rights`, `partitionEithers` |
| `System.IO` | 输入输出 | `readFile`, `writeFile`, `getLine` |
| `Control.Monad` | monad 操作 | `liftM`, `when`, `unless`, `join` |
| `Data.Function` | 函数工具 | `on`, `fix` |

```haskell
import Data.Map (Map)
import qualified Data.Map as Map

example :: Map String Int
example = Map.fromList [("a", 1), ("b", 2), ("c", 3)]
```

---

## 实战：完整模块设计示例

让我们设计一个处理配置的模块，展示最佳实践。

```haskell
-- File: App/Config.hs
module App.Config
  ( Config(..)
  , loadConfig
  , getHost
  , getPort
  ) where

import Data.Map (Map)
import qualified Data.Map as Map
import System.Environment (getEnv)

-- | 应用程序配置类型
data Config = Config
  { configHost :: String
  , configPort :: Int
  , configDebug :: Bool
  } deriving (Show)

-- | 从环境变量加载配置
loadConfig :: IO Config
loadConfig = do
  host <- getEnv "APP_HOST" `catch` \_ -> return "localhost"
  port <- read <$> getEnv "APP_PORT" `catch` \_ -> return "8080"
  debug <- (== "true") <$> getEnv "APP_DEBUG" `catch` \_ -> return "false"
  return Config
    { configHost = host
    , configPort = port
    , configDebug = debug
    }

-- | 获取服务器主机
getHost :: Config -> String
getHost = configHost

-- | 获取服务器端口
getPort :: Config -> Int
getPort = configPort
```

这个模块遵循了三个重要原则：第一，类型定义和数据构造器都不导出，使用者无法直接构造无效配置；第二，暴露的函数 `getHost` 和 `getPort` 提供了受控的访问方式；第三，所有配置加载逻辑封装在 `loadConfig` 中，调用者只需调用这个函数。

使用这个模块的代码：

```haskell
-- File: Main.hs
module Main where

import App.Config (Config, loadConfig, getHost, getPort)

main :: IO ()
main = do
  config <- loadConfig
  putStrLn $ "Server running at " ++ getHost config ++ ":" ++ show (getPort config)

避免常见陷阱

陷阱一：忘记模块声明位置。导入语句必须放在模块声明之后、代码之前：

module MyModule where  -- 先声明模块

import Data.List      -- 再导入依赖
import Data.Maybe

-- 函数定义放最后
myFunc :: [Maybe Int] -> [Int]
myFunc = catMaybes . map (\x -> x)

陷阱二：隐藏函数导致意外行为。使用 hiding 时要小心，确保隐藏的函数确实不需要：

-- 隐藏 head 可能导致 pattern match 失败
import Data.List hiding (head)

-- 安全做法：显式导入需要的函数
import Data.List (head)

陷阱三：循环导入。如果遇到 "Module imports form a cycle" 错误，检查模块依赖图，确保没有 A→B→A 的路径。

掌握 module 和 import 的用法是编写结构化 Haskell 程序的第一步。从今天开始，养成定义显式导出列表、使用 qualified 导入的习惯，你的代码会变得更清晰、更易维护。