az-device-contract-codegen 2026.5.18

Generate deterministic Modbus C, Markdown, and Tokio client artifacts from typed device contract definitions.
Documentation 
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
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129

use az_device_contract_codegen::{
    generate_bundle, ApiKind, ContractMethod, ContractRenderRequest, ContractService,
    ContractTypedItem, ReadReturnKind, RegisterArea, TransportKind, ValueType,
};

#[test]
fn should_generate_symmetric_artifacts_for_rtu_and_tcp() -> Result<(), Box<dyn std::error::Error>> {
    let request = ContractRenderRequest {
        transports: vec![TransportKind::Rtu, TransportKind::Tcp],
        services: vec![
            ContractService {
                api_kind: ApiKind::StaticRead,
                interface_name: "DeviceStaticReadApi".to_string(),
                interface_summary: Some("静态信息读取".to_string()),
                methods: vec![ContractMethod {
                    summary: Some("读取设备身份".to_string()),
                    method_name: "getDeviceIdentity".to_string(),
                    read_return_kind: Some(ReadReturnKind::Dto),
                    read_return_type_name: Some("DeviceIdentityRegisters".to_string()),
                    read_area: Some(RegisterArea::HoldingRegister),
                    write_area: None,
                    read_fields: vec![
                        ContractTypedItem {
                            name: "macAddress".to_string(),
                            summary: Some("MAC 地址".to_string()),
                            value_type: ValueType::String,
                        },
                        ContractTypedItem {
                            name: "flashCapacityKb".to_string(),
                            summary: Some("Flash 容量".to_string()),
                            value_type: ValueType::Int,
                        },
                    ],
                    parameters: vec![],
                }],
            },
            ContractService {
                api_kind: ApiKind::RuntimeRead,
                interface_name: "DeviceReadApi".to_string(),
                interface_summary: Some("运行态读取".to_string()),
                methods: vec![ContractMethod {
                    summary: Some("读取信号灯".to_string()),
                    method_name: "getSignalLights".to_string(),
                    read_return_kind: Some(ReadReturnKind::Dto),
                    read_return_type_name: Some("SignalLightsRegisters".to_string()),
                    read_area: Some(RegisterArea::DiscreteInput),
                    write_area: None,
                    read_fields: vec![
                        ContractTypedItem {
                            name: "ch1".to_string(),
                            summary: Some("第一路".to_string()),
                            value_type: ValueType::Boolean,
                        },
                        ContractTypedItem {
                            name: "ch2".to_string(),
                            summary: Some("第二路".to_string()),
                            value_type: ValueType::Boolean,
                        },
                    ],
                    parameters: vec![],
                }],
            },
            ContractService {
                api_kind: ApiKind::Write,
                interface_name: "DeviceWriteApi".to_string(),
                interface_summary: Some("写操作".to_string()),
                methods: vec![ContractMethod {
                    summary: Some("设置故障灯".to_string()),
                    method_name: "writeIndicatorLights".to_string(),
                    read_return_kind: None,
                    read_return_type_name: None,
                    read_area: None,
                    write_area: Some(RegisterArea::Coil),
                    read_fields: vec![],
                    parameters: vec![
                        ContractTypedItem {
                            name: "faultLightOn".to_string(),
                            summary: None,
                            value_type: ValueType::Boolean,
                        },
                        ContractTypedItem {
                            name: "runLightOn".to_string(),
                            summary: None,
                            value_type: ValueType::Boolean,
                        },
                    ],
                }],
            },
        ],
    };

    let bundle = generate_bundle(&request)?;

    assert!(
        bundle
            .artifacts
            .iter()
            .any(|artifact| artifact.file_name == "okm_modbus_rtu_tokio_client"),
        "缺少 RTU Rust 客户端产物"
    );
    assert!(
        bundle
            .artifacts
            .iter()
            .any(|artifact| artifact.file_name == "okm_modbus_tcp_tokio_client"),
        "缺少 TCP Rust 客户端产物"
    );
    let markdown = bundle
        .artifacts
        .iter()
        .find(|artifact| artifact.file_name == "modbus-rtu-contract")
        .ok_or("缺少 RTU 协议文档")?;
    assert!(
        markdown.content.contains("getSignalLights"),
        "协议文档中缺少方法映射"
    );
    let dispatch = bundle
        .artifacts
        .iter()
        .find(|artifact| {
            artifact.file_name == "okm_modbus_dispatch" && artifact.extension_name == "c"
        })
        .ok_or("缺少共享 dispatch 源文件")?;
    assert!(
        dispatch.content.contains("okm_bridge_get_signal_lights"),
        "共享 dispatch 未引用桥接函数"
    );
    Ok(())
}