Teamcenter 二次开发最佳实践：编码规范、异常处理与调试技巧

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

推荐环境：
├── Visual Studio（Windows C/C++ 开发）
├── Eclipse（Java + ITK 混合开发）
├── IntelliJ IDEA（纯 Java/SOA 开发）
└── VS Code（轻量级开发）

必备插件：
├── C/C++ 扩展（IntelliSense）
├── Java 扩展
├── Teamcenter 代码模板
└── 代码格式化工具

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

标准项目结构：
mycompany_tc_extensions/
├── src/
│   ├── itk/                    # ITK 扩展
│   │   ├── handlers/           # Handler 实现
│   │   ├── user_exits/         # User Exit 实现
│   │   └── utils/              # 工具类
│   ├── soa/                    # SOA 服务
│   │   ├── services/           # 服务实现
│   │   ├── dtos/               # 数据传输对象
│   │   └── converters/         # 转换器
│   ├── rac/                    # RAC 客户端扩展
│   │   ├── handlers/           # 命令 Handler
│   │   ├── views/              # 自定义视图
│   │   └── dialogs/            # 自定义对话框
│   └── web/                    # Web 扩展
│       ├── controllers/
│       └── views/
├── include/                    # 头文件
├── lib/                        # 依赖库
├── test/                       # 测试代码
├── config/                     # 配置文件
├── scripts/                    # 部署脚本
├── docs/                       # 文档
└── build/                      # 编译输出

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39

cmake_minimum_required(VERSION 3.15)
project(MyCompanyTCExtensions LANGUAGES C CXX)

set(CMAKE_C_STANDARD 11)
set(CMAKE_CXX_STANDARD 17)

# Teamcenter 路径
set(TC_ROOT "/opt/siemens/tc_root")
set(TC_INCLUDE "${TC_ROOT}/include")
set(TC_LIB "${TC_ROOT}/lib")

# 编译选项
add_compile_options(
    -Wall -Wextra -Wpedantic
    -Wno-unused-parameter
    -fPIC
)

# 包含目录
include_directories(
    ${TC_INCLUDE}
    ${PROJECT_SOURCE_DIR}/include
)

# 链接库
link_directories(${TC_LIB})

# Handler 示例
add_library(checkout_handler SHARED
    src/itk/handlers/checkout_handler.c
)
target_link_libraries(checkout_handler
    libitm_client
    libtc_crypto
)

# 安装
install(TARGETS checkout_handler
    DESTINATION ${TC_ROOT}/bin)

1
2
3

// 不检查返回值
ITEM_find_item(item_id, &item_tag);
AOM_save(item_tag);  // 如果 item_tag 无效，直接崩溃

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

// 检查每一步的返回值
status = ITEM_find_item(item_id, &item_tag);
if (status != ITK_ok || item_tag == NULLTAG) {
    EMH_store_error(EMH_severity_error,
        "找不到零部件: %s", item_id);
    return status;
}

status = AOM_save(item_tag);
if (status != ITK_ok) {
    char msg[256];
    EMH_get_error_string(NULLTAG, status, msg, sizeof(msg));
    EMH_store_error(EMH_severity_error,
        "保存零部件失败: %s, 错误码: %d, %s",
        item_id, status, msg);
    return status;
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49

// 每次获取资源后，确保释放
tag_t* item_list = NULL;
int count = 0;

status = ITEM_find_all_items(&count, &item_list);
if (status == ITK_ok && item_list != NULL) {
    for (int i = 0; i < count; i++) {
        process_item(item_list[i]);
    }
    // ⚠️ 必须释放
    MEM_free(item_list);
    item_list = NULL;
}

// 使用 goto cleanup 模式处理多资源
int complex_function() {
    tag_t tag1 = NULLTAG;
    tag_t tag2 = NULLTAG;
    char* buffer = NULL;
    int status = ITK_ok;

    status = get_first_resource(&tag1);
    if (status != ITK_ok) goto cleanup;

    status = get_second_resource(&tag2);
    if (status != ITK_ok) goto cleanup;

    buffer = (char*)MEM_alloc(1024);
    if (!buffer) {
        status = ITK_out_of_memory;
        goto cleanup;
    }

    // 主逻辑
    status = do_work(tag1, tag2, buffer);

cleanup:
    if (tag1 != NULLTAG) {
        // 释放 tag1（如需要）
    }
    if (tag2 != NULLTAG) {
        // 释放 tag2（如需要）
    }
    if (buffer) {
        MEM_free(buffer);
    }

    return status;
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

// 统一日志格式
#define LOG_DEBUG(format, ...) \
    tc_log_write(LOG_DEBUG_LEVEL, __FILE__, __LINE__, \
                 __func__, format, ##__VA_ARGS__)
#define LOG_INFO(format, ...) \
    tc_log_write(LOG_INFO_LEVEL, __FILE__, __LINE__, \
                 __func__, format, ##__VA_ARGS__)
#define LOG_WARN(format, ...) \
    tc_log_write(LOG_WARN_LEVEL, __FILE__, __LINE__, \
                 __func__, format, ##__VA_ARGS__)
#define LOG_ERROR(format, ...) \
    tc_log_write(LOG_ERROR_LEVEL, __FILE__, __LINE__, \
                 __func__, format, ##__VA_ARGS__)

// 使用示例
LOG_INFO("开始处理零部件: %s", item_id);
LOG_DEBUG("获取到 %d 个属性", prop_count);
LOG_WARN("属性值为空，使用默认值");
LOG_ERROR("保存失败，错误码: %d", status);

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

// 常见 ITK 错误码
#define ITK_ok                      0
#define ITK_error                   -1
#define ITK_aborted                 -2
#define ITK_ask_incomplete          -4
#define ITK_invalid_object          -15
#define ITK_user_cancel             -19
#define ITK_null_pointer            -20
#define ITK_out_of_memory           -21
#define ITK_invalid_argument        -22
#define ITK_internal_error          -38
#define ITK_not_implemented         -70
#define ITK_permission_denied       -93

// 错误处理模板
int handle_itk_error(int status, const char* context) {
    char error_msg[256];

    if (status == ITK_ok) return status;

    // 获取错误描述
    EMH_get_error_string(NULLTAG, status, error_msg, sizeof(error_msg));

    // 记录日志
    LOG_ERROR("%s 失败: 错误码=%d, 描述=%s", context, status, error_msg);

    // 存储到错误队列
    EMH_store_error(EMH_severity_error, "%s: %s", context, error_msg);

    return status;
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44

// Handler 标准模板
int my_checkout_handler(
    EPM_action_message_t msg
) {
    int status = ITK_ok;
    tag_t item_tag = NULLTAG;

    LOG_INFO("Handler 开始执行: %s", msg.action_name);

    // 1. 参数校验
    if (msg.n_evidences < 1) {
        LOG_ERROR("缺少证据对象");
        EMH_store_error(EMH_severity_error, "Handler 需要至少一个证据对象");
        return ITK_invalid_argument;
    }

    // 2. 获取上下文
    status = extract_context(msg, &item_tag);
    if (status != ITK_ok) {
        return handle_itk_error(status, "获取上下文");
    }

    // 3. 前置检查
    status = pre_checkout_check(item_tag);
    if (status != ITK_ok) {
        return handle_itk_error(status, "前置检查");
    }

    // 4. 主逻辑
    status = do_checkout_logic(item_tag);
    if (status != ITK_ok) {
        return handle_itk_error(status, "签出逻辑");
    }

    // 5. 后置处理
    status = post_checkout_cleanup(item_tag);
    if (status != ITK_ok) {
        LOG_WARN("后置处理失败，但不影响主流程: %d", status);
        // 不返回错误，允许主流程继续
    }

    LOG_INFO("Handler 执行完成");
    return ITK_ok;
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51

// SOA Service 异常处理
@Service
public class ItemServiceImpl implements ItemService {

    @Override
    public ServiceData createItem(CreateItemRequest request) {
        ServiceData serviceData = ServiceData.newInstance();

        try {
            // 1. 参数校验
            if (request.getItemId() == null || request.getItemId().isEmpty()) {
                throw new IllegalArgumentException("item_id 不能为空");
            }

            // 2. 业务逻辑
            ItemResult result = doCreateItem(request);

            // 3. 构建响应
            serviceData.setPayload(result);

        } catch (TCException e) {
            // Teamcenter 异常
            logger.error("TC 操作失败", e);
            serviceData.addErrorMessage(
                createErrorMessage("TC_ERROR", e.getMessage(), e));

        } catch (IllegalArgumentException e) {
            // 参数异常
            logger.warn("参数校验失败: {}", e.getMessage());
            serviceData.addErrorMessage(
                createErrorMessage("PARAM_ERROR", e.getMessage(), e));

        } catch (Exception e) {
            // 未知异常
            logger.error("未知异常", e);
            serviceData.addErrorMessage(
                createErrorMessage("UNKNOWN_ERROR", "系统内部错误", e));
        }

        return serviceData;
    }

    private ErrorMessage createErrorMessage(
        String code, String message, Throwable cause) {
        ErrorMessage em = new ErrorMessage();
        em.setCode(code);
        em.setMessage(message);
        em.setStackTrace(getStackTrace(cause));
        return em;
    }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

// 方法一：日志调试（最常用）
LOG_DEBUG("变量值: %d, %s, %p", int_val, str_val, ptr_val);

// 方法二：断点调试（需要调试符号）
// 编译时添加 -g 选项
// gcc -g -shared -o handler.so handler.c

// 方法三：GDB 远程调试
// 1. 在 TC Server 启动时附加调试参数
// tcserver.exe -debug

// 2. GDB 附加进程
// gdb -p <tcserver_pid>
// (gdb) break my_handler_function
// (gdb) continue

// 方法四：临时输出到文件
void debug_write(const char* format, ...) {
    FILE* fp = fopen("/tmp/tc_debug.log", "a");
    if (fp) {
        va_list args;
        va_start(args, format);
        vfprintf(fp, format, args);
        fprintf(fp, "\n");
        fclose(fp);
        va_end(args);
    }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

// 方法一：日志调试
@Slf4j
public class ItemServiceImpl {
    public void createItem(Request req) {
        log.debug("请求参数: {}", req);
        log.debug("当前用户: {}", AIF_utility.getCurrentUserId());
        // ...
    }
}

// 方法二：远程调试
// 1. TC Server 启动参数添加：
// -agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=5005

// 2. Eclipse/IDEA 配置 Remote Debug
// Host: tc_server_ip
// Port: 5005

// 方法三：单元测试
@Test
public void testCreateItem() {
    // 使用测试环境
    ItemService service = new ItemServiceImpl();
    CreateItemRequest request = new CreateItemRequest();
    request.setItemId("TEST-001");
    request.setName("Test Item");

    ServiceData result = service.createItem(request);
    assertNotNull(result);
    assertFalse(result.hasErrors());
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

// RAC 调试技巧：
// 1. 启动调试模式
// rac_client/eclipse.exe -consoleLog -debug

// 2. 查看控制台输出
// 所有 System.out.println 都会显示在控制台

// 3. 断点调试
// Eclipse Debug 配置：
// - 选择 RAC 启动配置
// - 添加断点
// - Debug As → Eclipse Application

// 4. 日志级别调整
// rac_client/configuration/config.ini
// osgi.log.level=DEBUG

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

// 性能分析：计时
#include <time.h>

void benchmark_handler() {
    struct timespec start, end;
    clock_gettime(CLOCK_MONOTONIC, &start);

    // 执行操作
    do_expensive_operation();

    clock_gettime(CLOCK_MONOTONIC, &end);

    long elapsed_ms = (end.tv_sec - start.tv_sec) * 1000 +
                      (end.tv_nsec - start.tv_nsec) / 1000000;
    LOG_INFO("操作耗时: %ld ms", elapsed_ms);
}

// 内存分析
void check_memory_usage() {
    struct mallinfo mi = mallinfo();
    LOG_DEBUG("内存使用: 已分配=%d, 空闲=%d, 总大小=%d",
              mi.uordblks, mi.fordblks, mi.arena);
}

1
2
3
4
5
6
7

// 错误：循环中查询数据库
for (int i = 0; i < item_count; i++) {
    ITEM_find_rev(item_list[i], "A", &rev_list[i]);  // N 次查询
}

// 正确：批量查询
ITEM_find_multiple_revs(item_count, item_list, "A", rev_list);  // 1 次查询

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

// 错误：多次查询相同数据
tag_t rev1, rev2;
ITEM_find_rev(item1, "A", &rev1);
// ...
ITEM_find_rev(item1, "A", &rev2);  // 重复查询

// 正确：缓存结果
tag_t rev_cache = NULLTAG;
if (rev_cache == NULLTAG) {
    ITEM_find_rev(item1, "A", &rev_cache);
}
rev1 = rev_cache;
rev2 = rev_cache;

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40

// 优化 1：延迟初始化
int lazy_init_handler(EPM_action_message_t msg) {
    static int initialized = 0;
    static Config_t* config = NULL;

    if (!initialized) {
        config = load_config();  // 只加载一次
        initialized = 1;
    }

    // 使用 config
    return ITK_ok;
}

// 优化 2：批量处理
int batch_update_handler(EPM_action_message_t msg) {
    // 收集所有需要处理的项目
    tag_t* items = collect_items(msg);
    int count = msg.n_evidences;

    // 批量操作
    AOM_set_multiple_properties(count, items, prop_names, prop_values);

    MEM_free(items);
    return ITK_ok;
}

// 优化 3：异步处理
int async_handler(EPM_action_message_t msg) {
    // 主 Handler 只记录任务
    tag_t task_id = create_async_task(msg);

    // 后台线程处理
    pthread_t thread;
    pthread_create(&thread, NULL, process_async_task, (void*)task_id);
    pthread_detach(thread);

    LOG_INFO("异步任务已创建: %p", task_id);
    return ITK_ok;
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43

#!/bin/bash
# deploy_tc_extension.sh
set -e

TC_ROOT="/opt/siemens/tc_root"
BACKUP_DIR="/opt/tc_backup/$(date +%Y%m%d_%H%M%S)"
EXTENSION_DIR="./build"

echo "=== Teamcenter 扩展部署 ==="

# 1. 备份现有文件
echo "备份现有文件..."
mkdir -p "$BACKUP_DIR"
cp "$TC_ROOT"/bin/my_*.so "$BACKUP_DIR/" 2>/dev/null || true

# 2. 停止服务
echo "停止 TC 服务..."
systemctl stop tc-server

# 3. 部署新文件
echo "部署新扩展..."
cp "$EXTENSION_DIR"/*.so "$TC_ROOT"/bin/

# 4. 设置权限
echo "设置权限..."
chmod 755 "$TC_ROOT"/bin/my_*.so
chown tcuser:tcgroup "$TC_ROOT"/bin/my_*.so

# 5. 更新配置
echo "更新配置..."
# 执行配置更新脚本
./update_config.sh

# 6. 启动服务
echo "启动 TC 服务..."
systemctl start tc-server

# 7. 验证
echo "验证服务状态..."
sleep 5
systemctl status tc-server --no-pager

echo "部署完成！"

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

#!/bin/bash
# rollback_tc_extension.sh
set -e

BACKUP_DIR=$(ls -td /opt/tc_backup/* | head -1)
TC_ROOT="/opt/siemens/tc_root"

echo "=== 回退到版本: $BACKUP_DIR ==="

# 停止服务
systemctl stop tc-server

# 恢复备份文件
cp "$BACKUP_DIR"/*.so "$TC_ROOT"/bin/

# 启动服务
systemctl start tc-server

echo "回退完成！"