C语言宏实现的模板代码应如何放置与设计？

问题背景 #

计划编写一套依赖类型参数的C语言宏模板库，以下为头文件写法的极简示例：

#define PAIR_TEMPLATE(Type) \
typedef struct { Type a[2]; } PAIR_ ## Type; \
Type Pair_ ## Type ## _Sum (PAIR_ ## Type *pPair);

PAIR_TEMPLATE(char)
PAIR_TEMPLATE(int)

上述宏展开后将得到如下代码：

typedef struct { char a[2]; } PAIR_char;
char Pair_char_Sum (PAIR_char *pPair);

typedef struct { int a[2]; } PAIR_int;
int Pair_int_Sum (PAIR_int *pPair);

Sum函数的实现同样可以通过宏模板编写：

#define PAIR_Sum_TEMPLATE(Type) \
Type Pair_ ## Type ## _Sum (PAIR_ ## Type *pPair) { \
  return (Type) (pPair->a[0] + pPair->a[1]); \
}

注：以上仅为极简演示，实际的模板包含多个其他函数，且支持几乎任意struct类型，可类比动态数组模板的使用场景。

库本身会针对部分内置数据类型提前展开模板，同时也需要支持库用户针对自定义类型使用该模板，目前遇到两个核心设计问题：

• 同一翻译单元内同名typedef重复展开会触发C语法错误，用户无法感知库内部已经为哪些类型做了展开，后续库版本更新新增内置类型展开时，还可能和用户自己写的展开逻辑冲突。是否需要在手册中要求用户手动加标记宏、用#ifndef块包裹展开逻辑？有没有更优方案？
• 如果把函数实现模板放在独立.c文件中和用户代码分单元编译，用户很难为自定义类型展开实现；如果把实现模板放在头文件中让用户在自身翻译单元展开，又很难避免同一类型的实现被重复展开。

可行成熟方案 #

重复typedef展开问题的解决 #

设想的标记宏守卫方案本身就是工业界同类C泛型库的标准做法，完全不需要让用户手动写守卫判断，直接把守卫逻辑封装进模板宏内部即可，用户全程无感知：

// 宏拼接辅助工具，解决宏参数展开优先级问题
#define PAIR_CONCAT_(a, b) a##b
#define PAIR_CONCAT(a, b) PAIR_CONCAT_(a, b)

#define PAIR_TEMPLATE(Type) \
  /* 检测该类型模板是否已经展开 */ \
  #ifndef PAIR_CONCAT(PAIR_TEMPLATE_DEFINED_, Type) \
  #define PAIR_CONCAT(PAIR_TEMPLATE_DEFINED_, Type) 1 \
  typedef struct { Type a[2]; } PAIR_##Type; \
  Type Pair_##Type##_Sum(PAIR_##Type *pPair); \
  #endif

这套逻辑完全内置，不管是库内部提前展开内置类型，还是用户后续手动展开自定义类型，甚至版本迭代新增内置类型的展开，只要宏被重复调用，预处理器就会直接跳过展开逻辑，根本不会产生重复typedef代码。
唯一需要注意的约束是：如果传入的类型是带空格、特殊符号的复合类型（比如struct MyStruct、unsigned long、const char*），直接拼接宏名会因为token拆分问题报错，这时候只需要让用户先用typedef给这类类型起一个不带空格、特殊符号的别名，再把别名传入模板即可，这个约束非常轻量，不会带来额外使用负担。

实现模板重复展开问题的解决 #

直接用C99标准支持的static inline修饰实现模板中的所有函数，不需要拆分翻译单元，从根源上避免重复定义问题：

#define PAIR_IMPL_TEMPLATE(Type) \
  /* 同声明模板加守卫，避免同一翻译单元内重复展开 */ \
  #ifndef PAIR_CONCAT(PAIR_IMPL_DEFINED_, Type) \
  #define PAIR_CONCAT(PAIR_IMPL_DEFINED_, Type) 1 \
  static inline Type Pair_##Type##_Sum(PAIR_##Type *pPair) { \
    return (Type)(pPair->a[0] + pPair->a[1]); \
  } \
  #endif

这套方案的优势非常明确：

• 加static修饰后，即使多个翻译单元都展开了同一个类型的实现，每个翻译单元内的函数都是局部符号，链接阶段不会出现重定义冲突
• 加inline修饰后，编译器不会为未被调用的函数生成冗余代码，开优化时还会自动内联短小的工具函数，性能比跨翻译单元调用更高，也不会因为多翻译单元重复展开导致目标文件体积膨胀
• 同样内置守卫宏，保证同一翻译单元内同类型的实现最多只展开一次

可以直接把声明模板和实现模板都放在公开头文件中，库内部提前展开内置类型时同时完成声明和实现的展开；用户需要使用自定义类型时，只需要在自己的代码里调用一次对应模板宏即可，完全不需要关心重复展开、版本兼容的问题，使用体验和C++模板基本一致。如果想进一步降低使用门槛，也可以直接把实现模板的逻辑嵌套进声明模板里，用户只需要调用一次PAIR_TEMPLATE(Type)就能自动完成声明+实现的展开，不需要额外调用实现宏。
这套方案是目前开源C泛型容器库的通用实现，兼容所有支持C99及以上标准的编译器，没有特殊黑魔法，长期维护成本很低。

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