C语言不完全类型：隐藏结构体细节，实现模块化封装

此前一篇关于嵌入式C语言中掩码结构体的文章似乎引起了一些讨论。这或许是因为宏的实现方式不易理解，也可能是其具体用法不够清晰。实际上，掩码结构体的核心思路是使用一个掩码数组 chMask 来对结构体进行访问保护。

要更好地理解其应用，可以结合查看 GorgonMeducer 大佬的 PLOOC（Protected Low-overhead Object-oriented C） 使用示例。

https://github.com/GorgonMeducer/PLOOC

同样的封装思想，也可以结合 C语言中的不完全类型（Incomplete Types） 来实现对结构体的保护，这是一种更为基础和常见的技巧。

什么是不完全类型？

在C/C++中，不完全类型指的是那些声明了但尚未完全定义的类型。常见的形式有 void 类型、未指定长度的数组，以及仅有标签（如 struct dynamic_array;）而没有成员列表的结构体或联合体。

使用不完全类型的指针或引用时，编译器不需要知道该类型的全部细节。例如，我们常这样声明一个外部数组：

extern int array[];

这里的 array 就是一个不完全类型的数组。通常，这类声明放在头文件（.h）中，而将完整的定义（包括数组长度）放在源文件（.c）里。这样做的好处是，当需要修改数组大小时，只需改动源文件，对外公开的头文件可以保持不变。

用数组举例可能还不够直观，下面我们通过一个结构体的具体案例来深入探讨。

首先思考一个问题：结构体的完整定义，应该放在头文件里，还是源文件里？

答案是：两种方式都可以，但它们带来的封装效果截然不同。

我们以一个动态数组（Dynamic Array） 的管理模块为例进行演示。动态数组与静态数组不同，其大小可以在程序运行时动态改变，内存从堆（heap）中分配，为有效利用存储空间提供了灵活性。

方案一：结构体定义在头文件中

假设我们有三个文件：dynamic_array.h, dynamic_array.c, main.c。

如果采用传统方式，dynamic_array.h 头文件可能会直接暴露结构体的内部细节：

在这个头文件中，我们虽然提供了一系列接口函数（如 DA_Init、DA_SetValue）来操作动态数组对象，但结构体 dynamic_array 的完整定义（包含 array 指针和 len 成员）也一览无余。

这会导致一个问题：使用者虽然可以调用你提供的接口，但他也能直接访问和修改结构体的内部数据。可能会有人写出下面这样的代码：

#include <stdio.h>
#include <stdlib.h>
#include "dynamic_array.h"

int main(void)
{
    /* 调用dynamic_array.h提供的接口 */
    dynamic_array_def *pArray = DA_Init();

    /* 直接操作数据！绕过了接口 */
    pArray->len = 10;
    pArray->array = (int*)realloc(pArray->array, pArray->len*sizeof(int));

    /* 调用dynamic_array.h提供的接口 */
    DA_Clean(pArray);
    return 0;
}

明明有设计良好的接口，使用者却偏要直接操作内部数据。这种做法极易出错，比如忘记分配内存、越界访问等。更令人无奈的是，如果因此出了bug，对方可能会理直气壮地说：“你把数据都暴露给我了，我为什么不能直接改？”

到头来，提供这个头文件的开发者还得“背锅”。这促使我们思考更好的C语言封装方式。

方案二：利用不完全类型，将结构体定义隐藏在源文件中

为了避免上述问题，我们可以修改头文件，使用不完全类型。

关键改动在于：头文件 dynamic_array.h 中不再包含结构体的成员列表，只进行一个前向声明（typedef struct dynamic_array dynamic_array_def;）。此时，dynamic_array_def 对于包含该头文件的模块来说，就是一个不完全类型。

结构体的完整定义被移到了源文件 dynamic_array.c 中。这样一来，外部的调用者（如 main.c）只知道 dynamic_array_def 是一个类型，但完全看不到它内部有什么数据成员。

这种设计巧妙地强制调用者必须使用我们提供的接口函数来操作对象，因为除了我们给出的函数原型，他们没有任何其他途径可以访问对象内部。这极大地增强了代码的封装性和模块间的解耦性，是编写高质量、易维护C语言库的常用技巧。

优点总结：

• 信息隐藏：有效保护了结构体的内部实现细节。
• 接口契约：强制使用者通过规定的接口进行交互，减少误用。
• 降低耦合：模块之间仅通过指针和接口通信，减少了编译依赖。

缺点注意：

• 不能对不完全类型使用 sizeof 运算符。
• 需要在实现源文件中保证定义的唯一性和正确性。

完整示例代码

以下是通过不完全类型实现动态数组保护的完整工程代码：

dynamic_array.h (头文件 - 对外接口)

#ifndef __DYNAMIC_ARRAY_H
#define __DYNAMIC_ARRAY_H

/* 前向声明，创建一个不完全类型 */
typedef struct dynamic_array dynamic_array_def;

/* 初始化dynamic_array */
dynamic_array_def *DA_Init(void);

/* 销毁dynamic_array */
void DA_Clean(dynamic_array_def *pThis);

/* 设置dynamic_array长度 */
void DA_SetSize(dynamic_array_def *pThis, unsigned len);

/* 获取dynamic_array长度 */
unsigned DA_GetSize(dynamic_array_def *pThis);

/* 设置dynamic_array某元素的值 */
int DA_SetValue(dynamic_array_def *pThis, unsigned index, int value);

/* 获取dynamic_array某元素的值 */
int DA_GetValue(dynamic_array_def *pThis, unsigned index, int *pValue);

#endif

dynamic_array.c (源文件 - 内部实现)

#include "dynamic_array.h"
#include <stdlib.h>

/* 结构体的完整定义仅在此处可见 */
struct dynamic_array
{
    int *array;
    unsigned len;
};

/* 初始化dynamic_array */
dynamic_array_def *DA_Init(void)
{
    dynamic_array_def *pArray = malloc(sizeof(dynamic_array_def));

    pArray->array = NULL;
    pArray->len = 0;
    return pArray;
}

/* 销毁dynamic_array */
void DA_Clean(dynamic_array_def *pThis)
{
    free(pThis->array);
    pThis->len = 0;
    free(pThis);
}

/* 设置dynamic_array长度 */
void DA_SetSize(dynamic_array_def *pThis, unsigned len)
{
    pThis->len = len;
    pThis->array = (int*)realloc(pThis->array, pThis->len * sizeof(int));
}

/* 获取dynamic_array长度 */
unsigned DA_GetSize(dynamic_array_def *pThis)
{
    return pThis->len;
}

/* 设置dynamic_array某元素的值 */
int DA_SetValue(dynamic_array_def *pThis, unsigned index, int value)
{
    if (index >= pThis->len)
    {
        return -1;
    }

    pThis->array[index] = value;
    return 0;
}

/* 获取dynamic_array某元素的值 */
int DA_GetValue(dynamic_array_def *pThis, unsigned index, int *pValue)
{
    if (index >= pThis->len)
    {
        return -1;
    }

    *pValue = pThis->array[index];
    return 0;
}

main.c (使用者代码)

#include <stdio.h>
#include <stdlib.h>
#include "dynamic_array.h"

int main(void)
{
    int arr_elem = 0;

    /* 初始化一个动态数组 */
    dynamic_array_def *pArray = DA_Init();

    /* 设置数组长度为10 */
    DA_SetSize(pArray, 10);

    /* 给数组元素赋值 */
    for (int i = 0; i < 10; i++)
    {
        DA_SetValue(pArray, i, i);
    }

    /* 遍历数组元素并打印 */
    for (int i = 0; i < 10; i++)
    {
        DA_GetValue(pArray, i, &arr_elem);
        printf("%d ", arr_elem);
    }

    /* 数组清理 */
    DA_Clean(pArray);

    return 0;
}

编译与运行
使用GCC编译并运行上述代码：

gcc main.c dynamic_array.c -o dynamic_array.exe
./dynamic_array.exe

程序将成功输出 0 1 2 3 4 5 6 7 8 9。

总结

通过不完全类型来保护C语言中的结构体，是一种简单而强大的封装技术。它将数据结构的实现细节隐藏在源文件中，仅通过头文件暴露操作接口。这种方法不仅提高了代码的安全性和健壮性，还使得模块之间的职责更清晰，耦合度更低，非常适合在云栈社区这类注重代码质量和可维护性的开发者社区中进行分享和探讨。无论是设计通用的函数库，还是构建复杂的嵌入式系统，掌握并运用这一技巧都大有裨益。