命名空间导出是开发者主动设计的接口组织策略，用于控制可见性、减少命名污染、提升调用清晰度；需显式声明稳定接口，按能力域分组导出，配合版本契约与工具链自动化验证。
命名空间导出（Namespace Export）不是 SDK 自动具备的功能，而是开发者在设计阶段主动采用的一种接口组织策略。它的核心作用是控制可见性、减少命名污染、提升调用清晰度，尤其适合大型 SDK 中模块多、类型杂、版本迭代频繁的场景。
明确导出边界，避免“全量暴露”
大型 SDK 往往包含大量内部工具类、中间结构体、调试辅助函数等，这些不该出现在用户 API 文档里。若不加约束，直接把整个包或头文件全量导出，会导致：
- 用户在 IDE 中看到大量无关符号，干扰关键接口识别
- 不同子模块的同名类型（如
Config、Error）发生冲突 - 内部实现变更时，意外破坏外部依赖（因为用户误用了非公开接口）
正确做法是：只在顶层命名空间（如 hms::ml 或 huawei::sdk::core）中显式声明哪些类、函数、常量是“对外承诺稳定”的，其余一律设为 private、internal 或未导出。
例如，在 C++ SDK 中可这样组织：
// hms_ml.h（唯一推荐包含的头文件）
namespace hms {
namespace ml {
// ✅ 显式导出的稳定接口
class ImageAnalyzer;
enum class RecognitionMode;
void InitSDK(const Config& config);
// ❌ 不导出：内部调度器、序列化工具、测试桩等
// namespace detail { ... }
} // namespace ml
} // namespace hms
按能力域分组导出，支持按需引入
用户不需要一次性加载全部功能。通过细分命名空间导出，可支持粒度更细的引用方式：
-
#include "hms/ml/vision.h"→ 只含图像识别相关接口 -
#include "hms/ml/speech.h"→ 只含语音识别与合成接口 -
#include "hms/ml/core.h"→ 含基础类型（Result、ErrorCode）和通用配置
每个子头文件仍遵循“只导出该域内稳定接口”原则，且彼此不互相 include 冗余内容。这样既降低编译依赖，也方便用户快速定位所需模块。
配合版本兼容策略，导出即契约
一旦某个符号出现在命名空间导出列表中，就代表它进入 SDK 的公共 ABI/SPI 契约。后续版本中：
- 不允许删除或重命名已导出的接口（除非走正式废弃流程）
- 参数类型变更需保持二进制兼容（如用
struct ConfigV2替代Config时，保留旧字段并标记[[deprecated]]） - 新增接口应放在新子命名空间（如
hms::ml::v2::ImageAnalyzer），避免污染原命名空间
这种约束看似严格，实则大幅降低下游集成风险——用户能放心写代码，不必担心下个 patch 版本突然 break build。
工具链配合：自动生成导出清单与文档
导出不是靠人工维护字符串列表。建议接入构建流程：
- 使用 Clang LibTooling 或 CMake 的
export_compile_commands提取所有被public标记或位于顶层命名空间的符号 - 将结果生成
exported_symbols.json，作为 CI 检查项：新增 PR 若修改了导出列表，必须附带兼容性说明 - 文档生成工具（如 Doxygen + custom filter）仅扫描导出命名空间下的注释，自动产出精简版 API 手册
这样，“命名空间导出”就从一个设计习惯，变成可验证、可追踪、可协作的工程实践。
不复杂但容易忽略
