Документация TarsGo

модуль TestApp
{
	
	интерфейс Hello
	{
	    int test();
	    int testHello(string sReq, out string sRsp);
	};
	
};	

go install $GOPATH/src/github.com/TarsCloud/TarsGo/tars/tools/tars2go

tars2go --outdir=./vendor hello.tars

пакет main

импортировать (
    "github.com/TarsCloud/TarsGo/tars"
```go
type serverConfig struct {
	Node      string
	App       string
	Server    string
	LogPath   string
	LogSize   string
	LogLevel  string
	Version   string
	LocalIP   string
	BasePath  string
	DataPath  string
	config    string
	notify    string
	log       string
	netThread int
	Adapters  map[string]adapterConfig
	Container string
	Isdocker  bool
	Enableset bool
	Setdivision string
}

type serverConfig struct {
	Node      string
	App       string
	Server    string
	LogPath   string
	LogSize   string
	LogLevel  string
	Version   string
	LocalIP   string
	BasePath  string
	DataPath  string
	config    string
	notify    string
	log       string
	netThread int
	Adapters  map[string]adapterConfig
	Container string
	Isdocker  bool
	Enableset bool
	Setdivision string
}

type adapterConfig struct {
	Host     string
	Port     int
	Protocol string
}

```xml
<tars>
  <application>
      enableset=Y
      setdivision=gray.sz.*
    <server>
       node=tars.tarsnode.ServerObj@tcp -h OnClickListener 10.120.129.226 -p 19386 -t 60000
       app=TestApp
       server=HelloServer
       localip=10.120.129.226
       local=tcp -h 127.0.0.1 -p 20001 -t 3000
       basepath=/usr/local/app/tars/tarsnode/data/TestApp.HelloServer/bin/
       datapath=/usr/local/app/tars/tarsnode/data/TestApp.HelloServer/data/
       logpath=/usr/local/app/tars/app_log/
       logsize=10M
       config=tars.tarsconfig.ConfigObj
       notify=tars.tarsnotify.NotifyObj
       log=tars.tarslog.LogObj
       #timeout for deactivating, ms.
       deactivating-timeout=2000
       logLevel=DEBUG
    </server>
  </application>
</tars>
```#### 1.5 Адаптер
Адаптер представляет привязку IP-адреса и порта для определённого объекта.
Пример реализации сервера `app.AddServant(imp, cfg.App + "." + cfg.Server + ".HelloObj")` обеспечивает привязку конфигурации адаптера и реализации для объекта `HelloObj`.
Пример конфигурации адаптера приведён ниже:
```diff
+ Пример конфигурации адаптера:

<tars>
  <application>
    <server>
       <!-- конфигурация каждого адаптера -->
       <TestApp.HelloServer.HelloObjAdapter>
            <!-- разрешенные IP для белого списка. -->
            allow
            <!-- IP и порт для прослушивания -->
            endpoint=tcp -h 10.120.129.226 -p 20001 -t 60000
            <!-- группа обработчиков -->
            handlegroup=TestApp.HelloServer.HelloObjAdapter
            <!-- максимальное количество подключений -->
            maxconns=200000
            <!-- протокол, только tars на данный момент -->
            protocol=tars
            <!-- максимальная емкость в очереди обработчиков -->
            queuecap=10000
            <!-- время ожидания в миллисекундах для запроса в очереди -->
            queuetimeout=60000
            <!-- сервант -->
            servant=TestApp.HelloServer.HelloObj
            <!-- потоки в обработчике серверной стороны реализации кода. goroutine для golang. -->
            threads=5
       </TestApp.HelloServer.HelloObjAdapter>
    </server>
  </application>
</tars>

./HelloServer --config=config.conf

Пользователь может легко написать код клиента без необходимости писать спецификацию протокола для коммуникации.
#### 2.1 Пример Клиента
Пример кода клиента:
```go
package main

import (
    "fmt"
    "github.com/TarsCloud/TarsGo/tars"
    "TestApp"
)

// tars.Communicator должен инициализироваться только один раз и быть глобальным
var comm *tars.Communicator

func main() {
    comm = tars.NewCommunicator()
    obj := "TestApp.TestServer.HelloObj@tcp -h 127.0.0.1 -p 10015 -t 60000"
    app := new(TestApp.Hello)
    comm.StringToProxy(obj, app)
    var req string = "Hello World"
    var out string
    ret, err := app.TestHello(req, &out)
    if err != nil {
        fmt.Println(err)
        return
    }
    fmt.Println(ret, out)
}

var comm *tars.Communicator
comm = tars.NewCommunicator()
comm.SetProperty("property", "tars.tarsproperty.PropertyObj")
comm.SetProperty("locator", "tars.tarsregistry.QueryObj@tcp -h ... -p ...")
```Описание:
 > * Формат конфигурационного файла коммуникатора будет описан позже.
 > * Коммуникаторы могут быть настроены без конфигурационного файла, и все параметры имеют значения по умолчанию.
 > * Коммуникатор также может быть инициализирован напрямую через метод `SetProperty`.
 > * Если вы не хотите использовать конфигурационный файл, вам необходимо самостоятельно задать параметр `locator`.

Описание атрибутов коммуникатора:
 > * `locator`: Адрес службы реестра должен быть в формате `"ip:port"`. Если вам не нужно, чтобы реестр находил службу, настройка этого параметра не требуется.
 > * `async-invoke-timeout`: Максимальное время ожидания (в миллисекундах) для клиентских вызовов. Значение по умолчанию для этой конфигурации равно 3000 миллисекундам.
 > * `sync-invoke-timeout`: В настоящее время не используется в tarsgo.
 > * `refresh-endpoint-interval`: Интервал (в миллисекундах) для периодического доступа к реестру для получения информации. Значение по умолчанию для этой конфигурации равно одной минуте.
 > * `stat`: Адрес службы, вызываемой между модулями. Если этот параметр не настроен, это означает, что отчетные данные будут пропущены.
 > * `property`: Адрес, по которому служба отчитывается о своих атрибутах. Если этот параметр не настроен, это означает, что отчетные данные будут пропущены.
 > * `report-interval`: В настоящее время не используется в tarsgo.
 > * `asyncthread`: В настоящее время не используется в tarsgo.> * modulename: Имя модуля, значение по умолчанию — имя исполняемого файла. Формат конфигурационного файла коммутирующего агента выглядит следующим образом:
 ```xml
 <tars>
   <application>
     <! -- Конфигурация, требуемая прокси -->
     <client>
         <! -- Адрес -->
         locator                     = tars. tarsregistry. QueryObj@tcp -h 127. 0. 0. 1 -p 17890
         <! -- Максимальное время ожидания (в миллисекундах) для синхронных вызовов -->
         sync-invoke-timeout         = 3000
         <! -- Максимальное время ожидания (в миллисекундах) для асинхронных вызовов -->
         async-invoke-timeout        = 5000
         <! -- Максимальное время ожидания (в миллисекундах) для синхронных вызовов -->
         refresh-endpoint-interval   = 60000
         <! -- Используется для межмодульных вызовов -->
         stat                        = tars. tarsstat. StatObj
         <! -- Адрес, используемый для отчета о свойствах -->
         property                    = tars. tarsproperty. PropertyObj
         <! -- Интервал отчета времени -->
         report-interval             = 60000
         <! -- Количество потоков, обрабатывающих асинхронные ответы -->
         asyncthread                 = 3
         <! -- Имя модуля -->
         modulename                  = Test. HelloServer
     </client>
   </application>
 </tars>

app := new(TestApp. Hello)
comm. StringToProxy(obj, app)
app. TarsSetTimeout(3000)
```#### 2.4 Интерфейс вызова

В этом разделе описывается, как клиент Tars вызывает сервер удаленно.

Сначала кратко описывается режим адресации клиента Tars. Затем будет введен метод вызова клиента, включая, но не ограничиваясь, односторонним вызовом, синхронным вызовом, асинхронным вызовом, хэш-вызовом и т. д.

##### 2.4.1 Введение в режим адресации

Режим адресации службы Tars обычно можно разделить на два способа: имя службы регистрируется в мастере, и имя службы не регистрируется в мастере. Мастер — это сервер имен (маршрутизационный сервер), предназначенный для регистрации информации о узлах службы.

Имя службы, добавленное в сервер имен, реализуется через платформу операционного управления.

Для служб, которые не зарегистрированы в мастере, их можно классифицировать как прямое адресование, то есть перед вызовом службы необходимо указать IP-адрес поставщика услуги. Клиенту необходимо указать конкретный адрес объекта HelloObj при вызове службы: то есть: Test.HelloServer.HelloObj@tcp -h 127.0.0.1 -p 9985

Test.HelloServer.HelloObj: Имя объекта

tcp: Протокол TCP

-h: Указывает адрес хоста, здесь это 127.0.0.1

-p: Порт, здесь это 9985Если HelloServer запущен на двух серверах, приложение инициализируется следующим образом:
```go
obj := "Test.HelloServer.HelloObj@tcp -h 127.0.0.1 -p 9985:tcp -h 192.168.1.1 -p 9983"
app := new(TestApp.Hello)
comm.StringToProxy(obj, app)

var *tars.Communicator
comm = tars.NewCommunicator()
comm.SetProperty("locator", "tars.tarsregistry.QueryObj@tcp -h ... -p ...")

package main

import (
    "fmt"
    "github.com/TarsCloud/TarsGo/tars"
    "TestApp"
)

var *tars.Communicator
func main() {
    comm = tars.NewCommunicator()
    obj := "TestApp.TestServer.HelloObj@tcp -h 127.0.0.1 -p 10015 -t 60000"
    app := new(TestApp.Hello)
    comm.StringToProxy(obj, app)
	var req string = "Hello World"
    var out string
    ret, err := app.TestHello(req, &out)
    if err != nil {
        fmt.Println(err)
        return
    }   
    fmt.Println(ret, out)
}

package main

import (
    "fmt"
    "github.com/TarsCloud/TarsGo/tars"
    "time"
    "TestApp"
)

var *tars.Communicator
func main() {
    comm = tars.NewCommunicator()
    obj := "TestApp.TestServer.HelloObj@tcp -h 127.0.0.1 -p 10015 -t 60000"
    app := new(TestApp.Hello)
    comm.StringToProxy(obj, app)
	go func() {
		var req string = "Hello World"
    	var out string
    	ret, err := app.TestHello(req, &out)
    	if err != nil {
        	fmt.Println(err)
        	return
    	} 
		fmt.Println(ret, out)
	}()
    time.Sleep(1)  
}
```##### 2.4.5 вызов по множеству
Клиент может вызвать сервер по множеству через конфигурационный файл, упомянутый выше. Включённое множество будет `y`, а разделение множества будет выглядеть как `gray.sz.*`. См. https://github.com/TarsCloud/Tars/blob/master/docs-en/tars_idc_set.md для получения дополнительной информации.
Если вы хотите вызвать по множеству вручную, то tarsgo будет поддерживать эту функцию в ближайшее время.
##### 2.4.6 Хэш-вызов
Так как несколько серверов могут быть развернуты, клиентские запросы распределяются случайным образом между серверами, но в некоторых случаях желательно, чтобы определённые запросы всегда отправлялись на определённый сервер. В этом случае Tars предоставляет простой способ для этого, который называется хэш-вызовом. Tarsgo будет поддерживать эту функцию в ближайшее время.### 3 Определение кода возврата TARS.
```go
// Определение кода возврата, предоставленного TARS-сервисом
const int TARSSERVERSUCCESS       = 0;    // Успешное выполнение на стороне сервера
const int TARSSERVERDECODEERR     = -1;   // Исключение декодирования на стороне сервера
const int TARSSERVERENCODEERR     = -2;   // Исключение кодирования на стороне сервера
const int TARSSERVERNOFUNCERR     = -3;   // Такой функции нет на стороне сервера
const int TARSSERVERNOSERVANTERR  = -4;   // Сервер не имеет объекта Servant
const int TARSSERVERRESETGRID     = -5;   // Несоответствие состояния сервера
const int TARSSERVERQUEUETIMEOUT  = -6;   // Превышение лимита очереди сервера
const int TARSASYNCCALLTIMEOUT    = -7;   // Превышение времени ожидания асинхронного вызова
const int TARSINVOKETIMEOUT       = -7;   // Превышение времени ожидания вызова
const int TARSPROXYCONNECTERR     = -8;   // Исключение соединения прокси
const int TARSSERVEROVERLOAD      = -9;   // Перегрузка сервера, превышение длины очереди
const int TARSADAPTERNULL         = -10;  // Маршрутизация клиента пустая, сервис не существует или все сервисы недоступны
const int TARSINVOKEBYINVALIDESET = -11;  // Нарушение правил вызова множества клиентом
const int TARSCLIENTDECODEERR     = -12;  // Исключение декодирования клиента
const int TARSSERVERUNKNOWNERR    = -99;  // Сервер находится в неизвестном состоянии
```### 4 Логи

Пример быстрого использования tarsgo вращающегося лога
```go
TLOG := tars.GetLogger("TLOG")
TLOG.Debug("Отладочное логирование")

```go
TLOG := tars.GetDayLogger("TLOG", 1)
TLOG.Debug("Отладочное логирование")

TLOG := GetRemoteLogger("TLOG")
TLOG.Debug("Отладочное логирование")

func helloAdmin(who string) (string, error) {
	return who, nil
}
tars.RegisterAdmin("tars.helloAdmin", helloAdmin)

// Функция должна быть в этом формате
type adminFn func(string) (string, error)

// затем вы должны зарегистрировать эту функцию с помощью

func RegisterAdmin(name string, fn adminFn)

Описание:
> * Обычно нам не нужно беспокоиться о статистическом отчете, так как фреймворк tarsgo выполняет этот отчет после каждого вызова клиента к серверу, независимо от того, был ли вызов успешным или неудачным. Успешность, неудачность, среднее время выполнения и другие данные будут отображаться в системе веб-управления при правильной настройке.
> * Если основной сервис развернут в системе веб-управления, вам не нужно определять Communicator и настраивать конфигурации tarsregistry, tarsstat и т.д., сервис будет автоматически отчитываться.
> * Если основной сервис или программа не развернуты в системе веб-управления, вам нужно определить Communicator, настроить tarsregistry, tarsstat и т.д., чтобы вы могли просматривать мониторинг вызываемого сервиса в системе веб-управления.
> * Отчетные данные отчитываются регулярно и могут быть настроены в конфигурации Communicator.


### 7 Отчет об аномалиях
Для лучшего мониторинга, фреймворк TARS поддерживает прямое отчетное сообщение об аномалиях в tarsnotify в программе, которое можно просмотреть на странице веб-управления.Фреймворк предоставляет три макроса для отчета о различных исключениях:
```go
tars.reportNotifyInfo("Ошибка получения данных из MySQL!")

```go
    sum := tars.NewSum()
    count := tars.NewCount()
    max := tars.NewMax()
    min := tars.NewMin()
    d := []int{10, 20, 30, 50} 
    distr := tars.NewDistr(d)
    p := tars.CreatePropertyReport("testproperty", sum, count, max, min, distr)
    for i := 0; i < 5; i++ {
        v := rand.Intn(100)
        p.Report(v)
    }   
```Описание:
> * Данные отчитываются регулярно и могут быть настроены в конфигурации коммуникатора; в настоящее время отчеты создаются один раз в минуту;
> * Создайте функцию PropertyReportPtr: параметр createPropertyReport может быть любой коллекцией статистических методов; пример использует шесть статистических методов, обычно требуется только один или два;
> * Обратите внимание, что при вызове createPropertyReport вы должны создать и сохранить созданный объект после включения сервиса, а затем просто использовать объект для отчета, не создавая его каждый раз при использовании.### 9 удалённая конфигурация
Пользователь может настроить удалённую конфигурацию из OSS. Подробнее см. в https://github.com/TarsCloud/TarsFramework/blob/master/docs-en/tars_config.md.
Это пример, иллюстрирующий, как использовать этот API для получения конфигурационного файла из удалённого источника.

```go
import "github.com/TarsCloud/TarsGo/tars"
...
cfg := tars.GetServerConfig()
remoteConf := tars.NewRConf(cfg.App, cfg.Server, cfg.BasePath)
config, _ := remoteConf.GetConfig("test.conf")

...

// количество рабочих потоков для обработки запросов от клиентов
// нулевое значение означает отсутствие контроля, один горутина для каждого запроса от клиента.
// runtime.NumCpu() обычно обеспечивает наилучшую производительность в тестах.
var MaxInvoke int = 0

const (
	// в настоящее время некоторые опции должны быть обновлены из удалённой конфигурации

	// версия
	TarsVersion string = "1.0.0"

	// сервер
)
```	AcceptTimeout time.Duration = 500 * time.Millisecond
	//нулевое значение означает отсутствие установки read deadline для Conn (лучшая производительность)
	ReadTimeout time.Duration = 0 * time.Millisecond
	//нулевое значение означает отсутствие установки write deadline для Conn (лучшая производительность)
	WriteTimeout time.Duration = 0 * time.Millisecond
	//нулевое значение означает отсутствие установки deadline для вызова пользовательского интерфейса (лучшая производительность)
	HandleTimeout time.Duration = 0 * time.Millisecond
	IdleTimeout   time.Duration = 600000 * time.Millisecond
	ZombileTimeout time.Duration = time.Second * 10
	QueueCap       int           = 10000000
``````md
### 11 Поддержка HTTP`tars.TarsHttpMux` похож на [http.ServeMux](https://golang.org/pkg/net/http/#ServeMux), параметр `pattern` используется как имя интерфейса в отчете мониторинга.

Вот пример HTTP-сервера:

```go
package main

import (
	"net/http"
	"github.com/TarsCloud/TarsGo/tars"
)

func main() {
	mux := &tars.TarsHttpMux{}
	mux.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
		w.Write([]byte("Hello tafgo"))
	})

	cfg := tars.GetServerConfig()
	tars.AddHttpServant(mux, cfg.App+"."+cfg.Server+".HttpObj") // Регистрация HTTP-сервера
	tars.Run()
}

type ContextTestImp struct {
}
// необходимо добавить параметр ctx context.Context
func (imp *ContextTestImp) Add(ctx context.Context, a int32, b int32, c *int32) (int32, error) {
	// Мы можем использовать контекст для получения полезной информации, такой как Client, IP, Port и информацию о трассировке
	// более подробно читайте в tars/util/current
	ip, ok := current.GetClientIPFromContext(ctx)
	if !ok {
		logger.Error("Ошибка получения IP из контекста")
	}  
	return 0, nil
}
// просто замените AddServant на AddServantWithContext
app.AddServantWithContext(imp, cfg.App+"."+cfg.Server+".ContextTestObj")
``Использование контекста клиента``````go

    ctx := context.Background()
    c := make(map[string]string)
    c["a"] = "b" 
// просто замените app.Add на app.AddWithContext, теперь вы можете передать контекст в фреймворк,
// если вы хотите установить контекст пакета запроса, вы можете передать опциональный параметр, такой как c, который является ...[string]string
    ret, err := app.AddWithContext(ctx, i, i*2, &out, c)

```
Чтобы ознакомиться с полным примером клиента и сервера, перейдите в examples/ContextTestServer


### 13 Фильтры и плагин Zipkin
Для поддержки написания плагинов мы добавили фильтры в фреймворк. У нас есть фильтры для клиента и сервера.

```go
// ServerFilter, dispatch и f передаются как параметры для перехвата реализации пользователя.
// req и resp это
type ServerFilter func(ctx context.Context, d Dispatch, f interface{}, req *requestf.RequestPacket, resp *requestf.ResponsePacket, withContext bool) (err error)
//
type ClientFilter func(ctx context.Context, msg *Message, invoke Invoke, timeout time.Duration) (err error)
// RegisterServerFilter регистрирует фильтр серверной части
// func RegisterServerFilter(f ServerFilter)
// RegisterClientFilter регистрирует фильтр клиента
// func RegisterClientFilter(f ClientFilter)

```Имея эти фильтры, теперь мы можем добавлять opentracing для каждого запроса.
Давайте посмотрим на фильтр клиента для opentracing.
```go
// ZipkinClientFilter возвращает фильтр клиента tars для подключения zipking opentracing.
func ZipkinClientFilter() tars.ClientFilter {
	return func(ctx context.Context, msg *tars.Message, invoke tars.Invoke, timeout time.Duration) (err error) {
		var pCtx opentracing.SpanContext
		req := msg.Req
		// Если контекст span передан в контекст, мы используем этот контекст как родительский span, иначе начинаем новый span.
		// Имя метода запроса rpc используется как имя span.
		if parent := opentracing.SpanFromContext(ctx); parent != nil {
			pCtx = parent.Context()
		}
		cSpan := opentracing.GlobalTracer().StartSpan(
			req.SFuncName,
			opentracing.ChildOf(pCtx),
			ext.SpanKindRPCClient,
		)
		defer cSpan.Finish()
		cfg := tars.GetServerConfig()
	}
}
```		// Устанавливаем дополнительную информацию для span, такие как метод, интерфейс, протокол, версия, IP и порт и т.д.
		cSpan.SetTag("client.ipv4", cfg.LocalIP)
		cSpan.SetTag("tars.interface", req.SServantName)
		cSpan.SetTag("tars.method", req.SFuncName)
		cSpan.SetTag("tars.protocol", "tars")
		cSpan.SetTag("tars.client.version", tars.TarsVersion)
``````md
// Внедряем контекст span в статус пакета запроса, который является map[string]string
if req.Status != nil {
	err = opentracing.GlobalTracer().Inject(cSpan.Context(), opentracing.TextMap, opentracing.TextMapCarrier(req.Status))
	if err != nil {
		logger.Error("ошибка внедрения span в статус:", err)
	}
} else {
	s := make(map[string]string)
	err = opentracing.GlobalTracer().Inject(cSpan.Context(), opentracing.TextMap, opentracing.TextMapCarrier(s))
	if err != nil {
		logger.Error("ошибка внедрения span в статус:", err)
	} else {
		req.Status = s
	}
}
// Ничего не меняем, просто вызываем запрос.
err = invoke(ctx, msg, timeout)
if err != nil {
	// Ошибка вызова, логируем информацию об ошибке в span.
	ext.Error.Set(cSpan, true)
	cSpan.LogFields(oplog.String("event", "error"), oplog.String("message", err.Error()))
}

return err
}
```

Сервер добавит фильтры, которые извлекают контекст span из статуса пакета запроса и начинают новый span.

Для примеров кода для сторон клиента и сервера, ознакомьтесь с ZipkinTraceClient и ZipkinTraceServer в разделе examples/TarsGo/tars/plugin/zipkintracing.