Файл Tars: описание

Tars — это протокол, основанный на IDL. Он похож на Protocol Buffer и является независимым от языка программирования. Это язык идентификаторов, похожий на C++, который используется для генерации файлов с интерфейсами конкретных сервисов. В то же время, как двоичный протокол, по сравнению с распространёнными текстовыми протоколами, такими как JSON, он обеспечивает более высокую эффективность кодирования и декодирования и занимает меньше места в сетевом пакете.

Файлы Tars используют расширение .tars. Для каждого сервиса в файле .tars при генерации кода будет создан интерфейс Java. Если генерируется код серверного интерфейса, будет добавлен суффикс Servant. Если код генерируется для клиента, будет добавлен суффикс Prx. Правила грамматики языка Tars можно найти в протоколе Tars.

Tars-maven-plugin

Плагин Tars-maven-plugin должен добавлять соответствующие зависимости в файл pom.xml:

<!--tars2java plugin-->
<plugin>
    <groupId>com.tencent.tars</groupId>
    <artifactId>tars-maven-plugin</artifactId>
    <version>1.7.0</version>
    <configuration>
        <tars2JavaConfig>
            <!-- tars file location -->
            <tarsFiles>
                <tarsFile>${basedir}/src/main/resources/hello.tars</tarsFile>
            </tarsFiles>
            <!-- Source file encoding -->
            <tarsFileCharset>UTF-8</tarsFileCharset>
            <!-- Generate server code -->
            <servant>false</servant>
            <!-- Generated source code encoding -->
            <charset>UTF-8</charset>
            <!-- Generated source code directory -->
            <srcPath>${basedir}/src/main/java</srcPath>
            <!-- Generated source code package prefix -->
            <packagePrefixName>com.tencent.tars.client.</packagePrefixName>
        </tars2JavaConfig>
    </configuration>
</plugin>

Некоторые конфигурации:

• tarsFiles: указывает расположение файла .tars;
• tarsFileCharset: формат кодировки исходного файла;
• servant: true означает генерацию серверного кода и интерфейса с суффиксом Servant, false означает генерацию клиентского кода и интерфейса с суффиксом Prx;
• charset: формат кодировки сгенерированного исходного кода;
• srcPath: каталог сгенерированных исходных кодов;
• packagePrefixName: префикс пакета сгенерированных исходных кодов.

Файл Tars на сервере

Возьмём hello.tars на стороне сервера в качестве примера:

module TestApp
{
    interface Hello
    {
        string hello(int no, string name);
    };
};

TestApp — это пространство имён, и все структуры и интерфейсы должны находиться в этом пространстве имён.

При генерации серверного кода необходимо установить тег servant в зависимости tars-maven-plugin в файле pom.xml равным true, а затем выполнить команду mvn tars: tars2java в корне проекта, чтобы получить файл интерфейса с суффиксом Servant — HelloServant.java:

@Servant
public interface HelloServant {

    public String hello(int no, String name);
}

После этого интерфейс может быть реализован в соответствии с бизнес-логикой.

Клиентский файл Tars

Когда вы делаете сервисный вызов на клиенте, вам сначала нужно получить файл tars на сервере, а затем вам нужно установить тег servant в зависимостях tars-maven-plugin в файле pom.xml равным false при генерации клиентского кода. Наконец, выполните команду mvn tars: tars2java в корневом каталоге проекта, чтобы получить файл интерфейса с суффиксом Prx — HelloPrx.java:

@Servant
public interface HelloPrx {

     String hello(int no, String name);

    CompletableFuture<String>  promise_hello(int no, String name);

     String hello(int no, String name, @TarsContext java.util.Map<String, String> ctx);

     void async_hello(@TarsCallback HelloPrxCallback callback, int no, String name);

     void async_hello(@TarsCallback HelloPrxCallback callback, int no, String name, @TarsContext java.util.map<String, String> ctx);
}

Интерфейс предоставляет три режима вызова:

• синхронный вызов;
• асинхронный вызов;
• вызов Promise.