拆分C语言类型定义后解引用为何出现不完整类型错误？

问题场景 #

原本可正常运行的单文件C程序，拆分为头文件、共享库实现文件和主程序文件并修改类型名后，编译主程序时出现以下错误：

door_key2_main.c:5:8: error: dereferencing pointer to incomplete type ‘door_key2_t’ {aka ‘struct door_key2_t’}
    5 |     dk2->pfnSet(dk2->self, 99);

错误原因 #

核心问题是**不完全类型（incomplete type）**导致的编译失败：

• 拆分后，头文件door_key2.h中仅做了结构体的类型声明：typedef struct door_key2_t door_key2_t;，但没有定义结构体的具体成员。
• 主程序door_key2_main.c包含头文件后，编译器只知道door_key2_t是一个结构体类型，但完全不清楚它的内部成员（比如pfnSet、self），因此无法直接通过指针访问这些成员。
• 原单文件程序中，结构体定义和主函数在同一个文件，编译器能看到完整的结构体成员，所以可以正常编译；拆分后结构体定义被隐藏在共享库实现文件door_key2.c中，主程序无法获取到这些信息。

解决方案 #

有两种处理方式，根据是否需要保持封装性选择：

方案1：暴露结构体定义（破坏封装，不推荐） #

将struct door_key2_t的完整定义移到头文件door_key2.h中，这样主程序就能看到结构体成员，编译错误会消失。但这种方式会暴露内部实现细节，违背模块化封装的初衷。

方案2：添加封装接口（推荐，保持模块化） #

在头文件中新增对外接口函数，代替主程序直接访问结构体成员，既解决编译问题，又保持封装性。

修改后的代码示例

• 头文件door_key2.h：

#ifndef DOOR_KEY2_H
#define DOOR_KEY2_H

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

typedef struct door_key2_t door_key2_t;

// 原有创建/销毁接口
door_key2_t *make_door_key2();
void destroy_door_key2(door_key2_t *self);

// 新增的操作接口
void door_key2_set_number(door_key2_t *self, int number);
int door_key2_get_number(door_key2_t *self);

#endif /* DOOR_KEY2_H */

• 实现文件door_key2.c：

#include "door_key2.h"

struct door_key2_t {
    door_key2_t *self;
    int number;
    void (*pfnSet)(door_key2_t *, int);
    int (*pfnGet)(door_key2_t *);
};

static int Get_door_key2_t(door_key2_t *self) {
    return self->number;
}

static void Set_door_key2_t(door_key2_t *self, int number) {
    if(NULL == self) {
        return;
    }
    self->number = number;
}

door_key2_t *make_door_key2() {
    door_key2_t *rv = (door_key2_t *)malloc(sizeof(door_key2_t));
    rv->self = rv;
    rv->number = 0;
    rv->pfnSet = Set_door_key2_t;
    rv->pfnGet = Get_door_key2_t;
    return rv;
}

void destroy_door_key2(door_key2_t *self) {
    free(self);
}

// 实现新增的接口函数
void door_key2_set_number(door_key2_t *self, int number) {
    if (self) {
        self->pfnSet(self->self, number);
    }
}

int door_key2_get_number(door_key2_t *self) {
    if (self) {
        return self->pfnGet(self->self);
    }
    return -1; // 返回错误标识
}

• 主程序door_key2_main.c：

#include "door_key2.h"

int main(int argc, char *argv[]) {
    door_key2_t *dk2 = make_door_key2();
    door_key2_set_number(dk2, 99);
    printf("This door key has the number %d\n", door_key2_get_number(dk2));
    destroy_door_key2(dk2);
    return 0;
}

修改后，主程序通过统一的接口操作对象，无需关心结构体内部细节，符合共享库模块化的设计目标，同时解决了编译错误。

内容的提问来源于stack exchange，提问作者Kérdezősködő Indián