Haskell数值优化库是否应开放内部中间函数的访问权限？

作为经常开发Haskell库的开发者，我可以明确告诉你：行业通用做法是绝对不要向库使用者暴露这类内部中间函数。这些函数是你的实现细节——命名晦涩、仅服务于上层逻辑，暴露出去只会污染公共API，给用户造成不必要的困惑，更重要的是会限制你后续重构的自由度：万一以后你要修改这些函数的签名、逻辑甚至删掉它们，都会直接破坏依赖这些内部函数的用户代码。

接下来针对你提到的两个核心痛点（代码可读性和测试便利性），结合Cabal给出具体的解决方案：

1. 代码可读性：用内部模块分层替代独立库拆分 #

你完全不需要把这些小型中间函数移到独立的Internal库，而是在当前库内部用模块分层来管理：

• 把对外提供的公共API放在顶层模块，比如Numeric.Optimization.GradientDescent，只导出完整的梯度下降函数这类用户需要的功能。
• 把中间函数放在同库的内部子模块，比如Numeric.Optimization.GradientDescent.Internal，这个模块只在库内部被主函数导入，不对外暴露。

这种方式的好处非常明显：

• 代码依然集中在同一个库里，主函数和它依赖的中间函数位置接近，你编写和维护时完全不会损失可读性。
• 公共API保持干净简洁，用户看不到任何无关的实现细节。

在你的.cabal文件里，只需要把内部模块标记为other-modules（而非exposed-modules）：

library
  exposed-modules:     Numeric.Optimization.GradientDescent
  other-modules:       Numeric.Optimization.GradientDescent.Internal
  -- 其他配置（base版本、hs-source-dirs等）...

other-modules里的模块不会被用户常规的import语句访问到（除非用户用{-# LANGUAGE PackageImports #-}强行导入，但这属于用户自己承担风险的行为，你不需要为此负责）。

2. 测试便利性：在Cabal测试套件中直接访问内部模块 #

Cabal的测试套件拥有对库所有模块的访问权限，包括other-modules里的内部模块。这意味着你可以在同一个测试套件里同时测试主函数和中间函数：

比如你的测试模块可以这样写：

module Test.GradientDescent where

import Numeric.Optimization.GradientDescent          -- 测试公共API的整体功能
import Numeric.Optimization.GradientDescent.Internal -- 测试中间单步函数的正确性
import Test.HUnit
import qualified Data.Vector as V

-- 测试中间函数的例子
testStep :: Test
testStep = TestCase $ do
  let gradient = V.fromList [2.0, 4.0]
      params = V.fromList [1.0, 1.0]
      learningRate = 0.1
      expected = V.fromList [0.8, 0.6]
      result = gradientDescentStep learningRate params gradient
  assertEqual "Gradient descent step calculation" expected result

-- 测试主函数的例子
testFullGradientDescent :: Test
testFullGradientDescent = TestCase $ do
  let costFunc x = V.sum (V.map (^2) x)
      gradFunc x = V.map (*2) x
      initialParams = V.fromList [3.0, 4.0]
      finalParams = gradientDescent costFunc gradFunc initialParams 0.1 100
  assertBool "Final params should be close to zero" (V.all (< 1e-6) (V.map abs finalParams))

tests :: Test
tests = TestList [testStep, testFullGradientDescent]

main :: IO ()
main = runTestTT tests >> return ()

然后在.cabal的测试部分配置：

test-suite optimization-tests
  type:                exitcode-stdio-1.0
  main-is:             Tests.hs
  hs-source-dirs:      test
  build-depends:       base >= 4.14 && < 5, your-library-name, HUnit, vector
  -- 其他配置...

这样你就能在同一个测试流程里，同时验证上层函数的整体功能和中间函数的正确性，完全不需要拆分库或者妥协。

额外小建议：给内部模块加明确的警告注释 #

在你的Internal模块顶部加一段注释，明确告知任何可能看到它的人（包括未来的你）这是内部实现：

-- | Internal implementation details for gradient descent algorithms.
--   WARNING: This module is NOT part of the public API.
--   Its contents may change, break, or disappear without prior notice.
module Numeric.Optimization.GradientDescent.Internal where

总结一下核心结论：

• 不暴露内部中间函数是Haskell库开发的行业共识，能保护公共API的稳定性和简洁性。
• 用Cabal的other-modules管理内部模块，既能保持代码的集中性和可读性，又能隔离实现细节。
• 测试套件可以自由访问内部模块，让你在同一位置完成所有测试。

内容的提问来源于stack exchange，提问作者hegash