Converter双向转换的边界条件处理

Converter双向转换的边界条件处理

一、背景分析

在气象数据交换业务中，BUFR 报文往往需要在旧版本（V23 系列）和新版本（GB/T 国标）之间进行双向转换。这种转换不仅涉及标识段版本号的修改，还包括数据段中要素值的提取、单位换算、缺测值处理以及模板不匹配时的降级策略。

bufrv2 的 converter.go 封装了 Converter 结构体，利用已有的 Encoder 和 Decoder 能力，实现了 OldToNew 和 NewToOld 两条转换链路。本文将重点分析其源码实现，以及在边界条件（如单位差异、版本号差异、数据子类型差异）上的处理策略。

二、Converter 的整体设计

2.1 结构定义

// Converter BUFR 转换器
type Converter struct {
	encoder Encoder
	decoder Decoder
}

// NewConverter 创建转换器
func NewConverter() *Converter {
	return &Converter{
		encoder: NewEncoder(),
		decoder: NewDecoder(),
	}
}

Converter 采用组合而非继承的方式，将编码器和解码器作为内部依赖注入。这种设计使得 Converter 可以很容易地替换为其他实现了 Encoder / Decoder 接口的自定义实现，便于单元测试时的 mock。

2.2 转换流程概览

无论是 OldToNew 还是 NewToOld，转换流程都遵循统一的"三段式"模式：

+----------+     +----------+     +----------+
|  解码源  | --> | 提取要素 | --> | 编码目标 |
|  BUFR   |     | 单位换算 |     |  BUFR   |
+----------+     +----------+     +----------+

以 OldToNew 为例：

func (c *Converter) OldToNew(oldData []byte, station *StationInfo) ([]byte, error) {
	// 1. 解析旧版数据
	decoded, err := c.decoder.Decode(oldData)
	if err != nil {
		return nil, fmt.Errorf("解析旧版数据失败: %w", err)
	}
	
	// 2. 转换为新版数据对象
	bufrData, err := c.convertToDataObject(decoded)
	if err != nil {
		return nil, fmt.Errorf("转换数据对象失败: %w", err)
	}
	
	// 3. 使用新版编码
	opts := &EncodeOptions{
		Version:   BufrVersionNew,
		WithQC:    true,
		UseBitmap: false,
	}
	
	return c.encoder.Encode(bufrData, station, opts)
}

NewToOld 的逻辑完全对称，只是 EncodeOptions.Version 改为 BufrVersionOld。

三、核心转换逻辑：convertToDataObject

convertToDataObject 是类型分发的入口，根据 decoded.BufrType 决定调用哪个具体的转换函数：

func (c *Converter) convertToDataObject(decoded *DecodedBufr) (BufrData, error) {
	switch decoded.BufrType {
	case BufrTypeAwsHour:
		return c.convertToAwsHourData(decoded)
	case BufrTypeAwsMinute:
		return c.convertToAwsMinuteData(decoded)
	case BufrTypeRadiateHour:
		return c.convertToRadiationHourData(decoded)
	default:
		return nil, fmt.Errorf("不支持的报文类型: %v", decoded.BufrType)
	}
}

四、地面小时数据转换与单位换算

4.1 convertToAwsHourData

func (c *Converter) convertToAwsHourData(decoded *DecodedBufr) (*AwsHourData, error) {
	data := &AwsHourData{
		ObservationTime: decoded.ObservationTime,
		Pressure:        &PressureHourInfo{},
		TempHumidity:    &TempHumidityHourInfo{},
		Rain:            &RainHourInfo{},
		Wind:            &WindHourInfo{},
		Weather:         &WeatherInfo{},
	}
	
	// 提取气压
	if val, ok := decoded.GetFloatValue(0, 10, 4); ok {
		data.Pressure.StationPress = &BufrField{Value: FormatFloat(ConvertPaToHpa(val), 1), QC: "0"}
	}
	if val, ok := decoded.GetFloatValue(0, 10, 51); ok {
		data.Pressure.SeaLevelPress = &BufrField{Value: FormatFloat(ConvertPaToHpa(val), 1), QC: "0"}
	}
	
	// 提取气温 (K -> °C)
	if val, ok := decoded.GetFloatValue(0, 12, 1); ok {
		tempC := ConvertKelvinToCelsius(val)
		data.TempHumidity.AirTemp = &BufrField{Value: FormatFloat(tempC, 1), QC: "0"}
	}
	
	// 提取湿度
	if val, ok := decoded.GetFloatValue(0, 13, 3); ok {
		data.TempHumidity.RelHumidity = &BufrField{Value: FormatFloat(val, 0), QC: "0"}
	}
	
	// 提取降水
	if val, ok := decoded.GetFloatValue(0, 13, 19); ok {
		data.Rain.Rain1H = &BufrField{Value: FormatFloat(val, 1), QC: "0"}
	}
	
	// 提取风
	if val, ok := decoded.GetFloatValue(0, 11, 1); ok {
		data.Wind.WindDir2Ms = &BufrField{Value: FormatFloat(val, 0), QC: "0"}
	}
	if val, ok := decoded.GetFloatValue(0, 11, 2); ok {
		data.Wind.WindSpeed2Ms = &BufrField{Value: FormatFloat(val, 1), QC: "0"}
	}
	
	// 提取天气现象
	if val, ok := decoded.GetFloatValue(0, 20, 3); ok {
		data.Weather.CurrentWeather = &BufrField{Value: FormatFloat(val, 0), QC: "0"}
	}
	
	return data, nil
}

4.2 单位换算边界条件

BUFR 新旧版本在部分要素的单位定义上存在差异。bufrv2 在 utils.go 中提供了专门的转换函数：

// ConvertHpaToPa 将 hPa 转换为 Pa
func ConvertHpaToPa(hpa float64) float64 {
	return hpa * 100
}

// ConvertPaToHpa 将 Pa 转换为 hPa
func ConvertPaToHpa(pa float64) float64 {
	return pa / 100
}

// ConvertCelsiusToKelvin 将摄氏度转换为开尔文
func ConvertCelsiusToKelvin(c float64) float64 {
	return c + 273.15
}

// ConvertKelvinToCelsius 将开尔文转换为摄氏度
func ConvertKelvinToCelsius(k float64) float64 {
	return k - 273.15
}

换算规则汇总表：

要素	旧版单位	新版单位	转换函数	说明
气压	hPa	Pa	ConvertPaToHpa / ConvertHpaToPa	差 100 倍
气温	°C	K	ConvertKelvinToCelsius / ConvertCelsiusToKelvin	差 273.15
相对湿度	%	%	无需转换	单位一致
降水	mm	kg/m²	当前实现按数值等价处理	近似等价
风速	m/s	m/s	无需转换	单位一致

在 convertToAwsHourData 中，ConvertPaToHpa 和 ConvertKelvinToCelsius 的调用体现了转换器对单位边界条件的显式处理。

4.3 缺测值与可选字段的边界

GetFloatValue 在内部已经处理了缺测值的情况：如果描述符对应值为缺测（全 1），或描述符在报文中不存在，都会返回 (0, false)。因此 Converter 中的转换代码采用了防御式编程：

if val, ok := decoded.GetFloatValue(0, 10, 4); ok {
    data.Pressure.StationPress = &BufrField{...}
}

这意味着：

• 字段存在但正常：正常提取并转换。
• 字段存在但缺测 ：ok == false，该字段保持 nil（后续编码时会生成缺测码）。
• 字段不存在（新版特有字段） ：ok == false，不会 panic。

五、分钟数据与辐射数据转换

5.1 分钟数据转换

func (c *Converter) convertToAwsMinuteData(decoded *DecodedBufr) (*AwsMinuteData, error) {
	data := &AwsMinuteData{
		ObservationTime: decoded.ObservationTime,
		Pressure:        &PressureInfo{},
		TempHumidity:    &TempHumidityInfo{},
		Rain:            &RainMinuteInfo{},
		Wind:            &WindMinuteInfo{},
	}
	
	if val, ok := decoded.GetFloatValue(0, 10, 4); ok {
		data.Pressure.StationPress = &BufrField{Value: FormatFloat(ConvertPaToHpa(val), 1), QC: "0"}
	}
	
	if val, ok := decoded.GetFloatValue(0, 12, 1); ok {
		tempC := ConvertKelvinToCelsius(val)
		data.TempHumidity.AirTemp = &BufrField{Value: FormatFloat(tempC, 1), QC: "0"}
	}
	
	if val, ok := decoded.GetFloatValue(0, 13, 11); ok {
		data.Rain.MinuteRain = &BufrField{Value: FormatFloat(val, 1), QC: "0"}
	}
	
	if val, ok := decoded.GetFloatValue(0, 11, 1); ok {
		data.Wind.WindDir2Ms = &BufrField{Value: FormatFloat(val, 0), QC: "0"}
	}
	if val, ok := decoded.GetFloatValue(0, 11, 2); ok {
		data.Wind.WindSpeed2Ms = &BufrField{Value: FormatFloat(val, 1), QC: "0"}
	}
	
	return data, nil
}

5.2 辐射数据转换

func (c *Converter) convertToRadiationHourData(decoded *DecodedBufr) (*RadiationHourData, error) {
	data := &RadiationHourData{
		ObservationTime: decoded.ObservationTime,
		Avg:             &RadiationAvgInfo{},
	}
	
	if val, ok := decoded.GetFloatValue(0, 14, 2); ok {
		data.Avg.Total = &BufrField{Value: FormatFloat(val, 0), QC: "0"}
	}
	
	if val, ok := decoded.GetFloatValue(0, 14, 4); ok {
		data.Avg.Scatter = &BufrField{Value: FormatFloat(val, 0), QC: "0"}
	}
	
	return data, nil
}

辐射数据目前提取的要素相对较少，这反映了辐射报文在实际业务中的字段覆盖边界------Converter 只处理已明确映射的字段，未映射字段保持缺测。

六、轻量级版本号修改：UpgradeVersion / DowngradeVersion

除了完整的"解码-重构-编码"转换链路外，Converter 还提供了两个轻量级方法，用于直接修改报文字节流中的版本号，而不改变数据内容。

6.1 升级版本号

func (c *Converter) UpgradeVersion(oldData []byte) ([]byte, error) {
	if len(oldData) < 24 {
		return nil, ErrInvalidBufrData
	}
	
	newData := make([]byte, len(oldData))
	copy(newData, oldData)
	
	section1Offset := 8
	
	if section1Offset+14 <= len(newData) {
		newData[section1Offset+13] = 43 // 新版主表版本号
	}
	if section1Offset+15 <= len(newData) {
		newData[section1Offset+14] = 1  // 新版本本地表版本号固定为1
	}
	
	return newData, nil
}

6.2 降级版本号

func (c *Converter) DowngradeVersion(newData []byte, bufrType BufrType) ([]byte, error) {
	if len(newData) < 24 {
		return nil, ErrInvalidBufrData
	}
	
	oldData := make([]byte, len(newData))
	copy(oldData, newData)
	
	section1Offset := 8
	
	if section1Offset+14 <= len(oldData) {
		oldData[section1Offset+13] = 23 // 旧版主表版本号
	}
	if section1Offset+15 <= len(oldData) {
		switch bufrType {
		case BufrTypeAwsMinute:
			oldData[section1Offset+14] = 1
		case BufrTypeAwsHour:
			oldData[section1Offset+14] = 3
		default:
			oldData[section1Offset+14] = 1
		}
	}
	
	return oldData, nil
}

适用场景对比：

方法	处理方式	数据内容是否改变	适用场景
OldToNew / NewToOld	完整解码+重构+编码	是（模板、单位适配）	需要严格按目标版本规范生成报文
UpgradeVersion / DowngradeVersion	直接修改字节	否	仅需要修改版本标识，数据内容已兼容

七、DecodeAndConvert：可读格式转换

DecodeAndConvert 提供了一条非 BUFR 的输出路径，将 BUFR 报文转换为 JSON 友好的 ConvertedResult：

func (c *Converter) DecodeAndConvert(data []byte) (*ConvertedResult, error) {
	decoded, err := c.decoder.Decode(data)
	if err != nil {
		return nil, err
	}
	
	result := &ConvertedResult{
		Version:         decoded.Version,
		BufrType:        decoded.BufrType,
		ObservationTime: decoded.ObservationTime,
		StationInfo:     decoded.ExtractStationInfo(),
		Elements:        make(map[string]interface{}),
	}
	
	if decoded.Section4 != nil {
		for _, val := range decoded.Section4.Values {
			key := val.Descriptor.String()
			if val.IsMissing {
				result.Elements[key] = nil
			} else {
				result.Elements[key] = val.Value
			}
			if val.Descriptor.Name != "" {
				result.Elements[val.Descriptor.Name] = result.Elements[key]
			}
		}
	}
	
	return result, nil
}

该方法同时保存了 F/X/Y 键和中文名称键，便于前端展示和日志调试。

八、总结

bufrv2 的 Converter 在设计上体现了"分层处理、边界显式、降级兼容"的思想：

1. 分层转换：解码 -> 数据对象转换 -> 编码，三层职责清晰，便于独立测试。
2. 单位边界显式处理 ：通过 ConvertPaToHpa、ConvertKelvinToCelsius 等函数，将新旧版本的单位差异收敛到一处。
3. 缺测安全 ：所有字段提取都通过 ok 判断，缺测或不存在的字段不会导致 panic。
4. 轻量级版本切换 ：UpgradeVersion / DowngradeVersion 提供了无需重构的快捷通道，适用于兼容性格式转换场景。

https://github.com/0voice