文章 | xtream-codec

实体编解码器调试

介绍

只需要给 EntityCodec 的 encode 或 decode 方法传入一个 CodecTracker 实例即可追踪每个字段的编解码详情。

注意

警告

CodecTracker 的设计目的仅仅是用来调试。会对编解码性能产生一定影响。

xtream-codec2025/3/2小于 1 分钟

实体编解码器

介绍

提示

这里介绍的是 io.github.hylexus.xtream.codec.core.EntityCodec

EntityCodec 用来支持基于注解的编解码。这里的注解指的是前面提到的：

@XtreamField()
@Preset.RustStyle.xxx()
@Preset.JtStyle.xxx()
自定义注解 ...

xtream-codec2025/3/1小于 1 分钟

参数解析器

介绍

这里说的 参数解析器 指的是 XtreamHandlerMethodArgumentResolver。

名字比较长，但从命名中可以看出来它本质上是一个 方法参数的解析器。

下面代码段中 processMessage0200V2019 方法的所有参数都是通过 XtreamHandlerMethodArgumentResolver 解析出来的：

@Component
@Jt808RequestHandler
public class DemoJt808RequestHandler {

    @Jt808RequestHandlerMapping(messageIds = 0x0200, versions = Jt808ProtocolVersion.VERSION_2019)
    @Jt808ResponseBody(messageId = 0x8001, maxPackageSize = 1000)
    public Mono<ServerCommonReplyMessage> processMessage0200V2019(
            XtreamExchange exchange,
            XtreamSession xtreamSession,
            XtreamRequest xtreamRequest,
            Jt808Request jt808Request,
            DefaultXtreamRequest defaultXtreamRequest,
            XtreamResponse xtreamResponse,
            DefaultXtreamResponse defaultXtreamResponse,
            Jt808RequestEntity<BuiltinMessage0200> requestEntity,
            @Jt808RequestBody DemoLocationMsg01 msg01,
            @Jt808RequestBody DemoLocationMsg02 msg02,
            @Jt808RequestBody ByteBuf buf01,
            @Jt808RequestBody ByteBuf buf02,
            @Jt808RequestBody(bufferAsSlice = false) ByteBuf buf03,
            @Jt808RequestBody(bufferAsSlice = false) ByteBuf buf04) {

        log.info("v2019-0x0200: {}", msg01);
        assertNotSame(buf01, buf02);
        assertNotSame(buf01, buf03);
        assertSame(buf03, buf04);
        assertSame(exchange.request(), xtreamRequest);
        assertSame(exchange.request(), jt808Request);
        assertSame(exchange.request(), defaultXtreamRequest);
        assertSame(exchange.response(), xtreamResponse);
        assertSame(exchange.response(), defaultXtreamResponse);
        final ServerCommonReplyMessage responseBody = ServerCommonReplyMessage.success(jt808Request);
        return Mono.just(responseBody);
    }
    
}

xtream-codec2024/12/10小于 1 分钟

扁平化写法示例

提示

在阅读本文之前，建议先阅读协议格式说明
所谓的 扁平化写法 就是不用单独封装 Header 和 Body，而是直接将 Header 和 Body 的数据写在同一个实体类中

hylexus2024/3/24小于 1 分钟

嵌套写法示例

提示

在阅读本文之前，建议先阅读协议格式说明
所谓的 嵌套写法 就是将 Header 和 Body 分别封装到单独的实体类中。

hylexus2024/3/24小于 1 分钟

内置注解

请先读我

内置注解都是从 @XtreamField 注解扩展而来的。目前有两种风格的注解：

Rust 数据类型命名风格
JT/T 808 协议数据类型命名风格

提示

强烈推荐优先使用 Rust 风格内置注解
- 数据类型比较全面
  - JT/T 808 风格的注解只支持无符号，因为 JT/T 808 官方文档里都是无符号数
- 支持小端序
不推荐直接使用底层的 @XtreamField 注解
- 虽然功能最完整，但是使用略显繁琐
- 但是如果你要自定义注解，那非常推荐使用 @XtreamField 来进行扩展

xtream-codec2024/3/10大约 4 分钟

自定义注解

自定义注解都是通过元注解 @XtreamField 的来实现的。

本示例将演示通过 @XtreamField 来实现一个自定义的日期注解。

注解定义

注解声明


@Target({ElementType.FIELD})
@Retention(RetentionPolicy.RUNTIME)
@Documented
@XtreamField(fieldCodec = MyDateTypeFieldCodec.class, dataType = BeanPropertyMetadata.FiledDataType.basic)
public @interface MyDateType {

    @AliasFor(annotation = XtreamField.class, attribute = "order")
    int order() default -1;

    @AliasFor(annotation = XtreamField.class, attribute = "condition")
    String condition() default "";

}

xtream-codec2024/3/10大约 1 分钟

数据类型

1.整数类型

长度	符号位	JavaType	Rust风格注解	JT风格注解
1	无	`byte/Byte`	`@Preset.RustStyle.u8`	`@Preset.JtStyle.Byte`
1	有	`short/Short`	`@Preset.RustStyle.i8`	--
2	无	`short/Short`	`@Preset.RustStyle.u16`	`@Preset.JtStyle.WORD`
2	有	`int/Integer`	`@Preset.RustStyle.i16`	--
4	无	`int/Integer`	`@Preset.RustStyle.u32`	`@Preset.JtStyle.DWORD`
4	有	`long/Long`	`@Preset.RustStyle.i32`	--
8	无	`long/Long`	`@Preset.RustStyle.u64`	--

xtream-codec2024/3/10小于 1 分钟

@XtreamField

介绍

@XtreamField 是最基础的注解。

内置的 别名(Alias) 注解 @Preset.RustStyle.xxx 和 @Preset.JtStyle.xxx 都是基于 @XtreamField 这个基础注解衍生的。

提示

注解别名都是依赖于 Spring 的 @org.springframework.core.annotation.AliasFor 注解实现的。

xtream-codec2024/3/10大约 2 分钟

扁平化写法示例

提示

在阅读本文之前，建议先阅读协议格式说明
所谓的 扁平化写法 就是不用单独封装 Header 和 Body，而是直接将 Header 和 Body 的数据写在同一个实体类中

hylexus2024/3/9小于 1 分钟