Если вы видите что-то необычное, просто сообщите мне. Skip to main content

Злоупотребление синтаксисом Go для создания DSL(предметно-ориентированного языка)

Go частый выбор для создания внутреностей высокопроизводительных систем, но так он так же разработан с некоторым количеством функций которые хороши для создания высокоуровневых абстракций. Вам не нужно переключаться на динамические языки такие как Ruby или Python, чтобы получить удовольствие от API или объяснительный синтакс.

Довольно часто для выражения API используется DSL(Предметно ориентированный язык). DSL это язык внутри языка который компилируется или интерпритируется внутри языка, в нашем случае Go. Если API хорошо спроектирован, DSL выглядит как его собственная спецификация специально созданная для конкретной задачи. DSL такие как CSS, SQL созданы как отдельный язык с их собственными анализаторами, но на данный момент мы сосредоточимся на одном, который построим с помощью компилятора Go, и используем внутри Go кода.

DSL используется для инфраструктурной автоматизации, модель объявления данных, построения запросов и тонны других приложений. Он может быть приятен для написания DSL для задач типа "подключил и настроил" потому, что они предлагают декларативный синтакс. Чаще чем инперативное описание, вся логика и операции нужны чтобы создать у приложения определенное состояние. DSL позволяет вам объявить желаемое состояние,параметры этого состояния и их реализацию ниже, всего лишь в шаге друг от друга. Конечный код тоже будет старатся выглядеть проще для понимания.

Мы собираемся посмотреть на то, как построить API, которое будет понятно для Go комплиятора, но выглядеть оно будет как отдельный язык. Название этой статьи выбрано потому, что мы собираемся нарушить дух Go только слегка, чтобы поправить букву закона так как нам хочется. Я надеюсь вы собираетесь быть рассудительны при применении сомнительных практик обсуждаемых далее. Я так же надеюсь изучая их, вы будете вдохновлены думать креативно о том, как писать выразительные Go API с которыми будет приятно работать и легко понимать.

Пример использования.

Мы собираемся построить просто DSL для создания HTTP посредника. Эта область отличный кандидат для DSL потому что оно наполнено общими, хорошо понимаемыми и часто переиспользуемыми шаблонами как ограничени доступа, частого ограничения, обработки сессии и так далее. Лучше всего для читалей и писателей кода который реализует эти шаблоны, если код будет читаться как декларативный файл настроек, чем как императивное изобретение колеса.

Личные типы.

Один из тонких но мощных моментов написания Go кода с образным чувством личности типов. Большую часть времени когда мы объявляем свой тип в Go, мы объявляем структуру или интерфейс. Мы так же можем объявить новый личный тип для существующих, ссылаясь на них с именем которое мы выбрали.

Это может быть чем-то простым как создание нового имени простопу типу, такому как string для названий хостов:

type Host string

Мы также можем создать тип для набора:

type HostList []Host
type HostSet map[Host]interface{}

Теперь где нибудь в нашем коде, переменная типа HostList будет []Host, или на самом деле []string под капотом, но с более понятным имененм.

Выгоду от таких типов, кроме как внешнего вида и сохраненных нажатий клавиш, это то что эти типы могут быть расширены с помощью их собственных типов. На пример:

func (s HostSet) Add(n Host) {
	s[n] = struct{}{}
}

func (s HostSet) Remove(n Host) {
	delete(s, n)
}

func (s HostSet) Contains(n Host) bool {
	_, found := s[n]
	return found
}

Как мы можем использовать HostSet как если бы это был более сложная структура контейнера доступная через методы:

func main() {
	s := make(HostSet)
	s.Add("golang.org")
	s.Add("google.com")
	s.Add("gopheracademy.org")
	s.Remove("google.com")

	hostnames := HostList{
		"golang.org",
		"google.com",
		"gopheracademy.org",
	}
	for _, n := range hostnames {
		fmt.Printf("%s? %v\n", n, s.Contains(n))
	}
}

Вот что мы получим на выходе:

golang.org? true
google.com? false
gopheracademy.org? true

Что мы тут имеем? Мы созадли абстракцию над простой мапой, мы можем использовать её как набор - у нее есть Add и Remove операции, и у нее есть проверка Contains - созданные нами обороты речи, которые могут быть использованны нами в коде. Он лучше изолирован, чем простая передача map[string]interface{} и надеясь что значение "набор имен хостов" соблюдается при доступе к map. Это решение более гибкое и явное, чем скажем:

func SetContains(s map[string]interface{}, hostname string) bool {
	_, found := s[hostname]
	return found
}

func main() {
	s := make(map[string]interface{})
	if SetContains(s, hostname) {
        // do stuff
	}
}

Поэкспериментируем чуток с созданием новых типов, частично для различных типов срезов и мапов, и даже для каналов. Какие обороты вы можете создать чтобы заставить работать эти типы проще и понятнее?

Высокоуровневые функции.

Go включает некоторые идеи из функционального программирования которое бесценно для создания выразительных и декларативных API. Go предлагает возможность присваивать функции переменных, для передачи функций как аргумент в другую функцию и для создания анонимных функций и закрытий. Используя высокоуровневые функции которые создают, изменяют, или строят поведение других функций, вы можете легко объединять кусочки логики и функциональности во что-то более сложное целое используя несколько выражений, чаще чем повторение или создание клубка условной логики.

Давайте построим наш пример выше по-новому. Добавим метод в HostList который принимает функцию как входной параметр и возвращает новый HostList:

func (l HostList) Select(f func(Host) bool) HostList {
	result := make(HostList, 0, len(l))
	for _, h := range l {
		if f(h) {
			result = append(result, h)
		}
	}
	return result
}

Этот метод HostList имеет эффективность создания нового HostList для которого предоставленное условие (func f) верно. Создадим простое выражение функции для вставки в f:

// import “strings” 
func IsDotOrg(h Host) bool {
	return strings.HasSuffix(string(h), ".org")
}

И используем его в наше новом методе HostList

myHosts := HostList{"golang.org", "google.com", "gopheracademy.org"}
fmt.Printf("%v\n", myHosts.Select(IsDotOrg))

Вывод будет таким:

[golang.org gopheracademy.org]

Select возвращает только те элементы myHosts для которых переданная функция IsDotOrg будет возвращать true, то есть для тех имен у которых есть ".org".

func(Host) bool немного кривовата как параметричечкий тип и создает подпись метода Select сложно для чтения, поэтому давайте используем наш трюк для типов, чтобы сделать его аккуратным.

type HostFilter func(Host) bool

Он делает Select более читаемым:

func (l HostList) Select(f HostFilter) HostList {
        //...
}

и добавляет выгоду с которой мы можем объявить некоторые методы HostFilter:

func (f HostFilter) Or(g HostFilter) HostFilter {
    return func(h Host) bool {
        return f(h) || g(h)
    }
}

func (f HostFilter) And(g HostFilter) HostFilter {
    return func(h Host) bool {
        return f(h) && g(h)
    }
}

Если мы хотим Ifобъявить weфункцию wantкоторая toможет declareиспользовать aHostFilter functionметода, thatк canсожалению useнам theseнжуно пойти другим путём, чтобы это сделать. Чтобы функция имела верный приемни HostFilter methods,метода, unfortunatelyнедостаточно weсовпадать willописанию needHostFilter, toнам goнужно aобъявить bitфункцию outкак ofHostFilter our way to do so. For a function to be a valid receiver of HostFilter methods, it’s not sufficient to match the signature of a HostFilter, we need to declare the function as a HostFilter explicitly:явно.

1 2 3

var IsDotOrg HostFilter = func(h Host) bool {
	return strings.HasSuffix(string(h), ".org")
}

Но теперь стало ясно что мы начали делать хорошо Unfortunately here it becomes clear that we have begun to make good on our threat to “abuse” Go’s syntax. Declaring a function by assigning an anonymous function to a variable gives an unclean feeling. Note that this isn’t required to use higher-order functions, or to take advantage of a type identity for a function signature - any func(Host) bool can be assigned to a HostFilter variable or parameter. This hare-brained declaration is only needed to be able to use functions like IsDotOrg as the receiver of the HostFilter methods.

The payoff, though, is that going to these lengths to allow our HostFilter functions to use these methods enables an interesting syntax:

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16

var HasGo HostFilter = func (h Host) bool { return strings.Contains(string(h), "go") }

var IsAcademic HostFilter = func(h Host) bool { return strings.Contains(string(h), "academy") }

func main() { myHosts := HostList{"golang.org", "google.com", "gopheracademy.org"} goHosts := myHosts.Select(IsDotOrg.Or(HasGo)) academies := myHosts.Select(IsDotOrg.And(IsAcademic))

fmt.Printf("Go sites: %v\n", goHosts)
fmt.Printf("Academies: %v\n", academies)

}

Running this gets:

1 2

Go sites: [golang.org google.com gopheracademy.org] Academies: [gopheracademy.org]

We can see a language of our own taking shape in an expression like myHosts.Select(IsDotOrg.Or(HasGo)). It reads a bit like English, if a little like something you might hear in the swamps of Dagobah. The declarative syntax has begun to emerge - the expression says more about the desired result (“select the elements of myHosts that are .orgs or contain ‘Go’) than it does about the specific steps required to get there. We used higher-order functions, Select, And, and Or, to compose behaviors from three different pieces of code in an entirely dynamic way.

This is a powerful way of expressing behavior, but all of this method chaining can start to get muddled:

1 2

// etc. myHosts.Select(IsDotOrg.Or(HasGo).Or(IsAcademic).Or(WelcomesGophers).And(UsesSSL)

So perhaps we can clean things up by using a variadic method:

1 2 3 4 5 6 7

var HostFilter Or = func (clauses ...HostFilter) HostFilter { var f HostFilter = nil for _, c := range clauses { f = f.Or(c) } return f }

and then rewrite the chained invocation above as:

1

myHosts.Select(Or(IsDotOrg, HasGo, IsAcademic, WelcomesGophers).And(UsesSSL))

Another warning: these functional-style constructs are some of the most dangerously powerful features of Go - all of the truly unreadable Go I’ve ever read and most of the truly unreadable Go I’ve ever written got to be that way by abusing these features, creating anonymous functions and passing them through layer after layer of indirection.

Nevertheless, the dynamism of functional-style programming is invaluable when building our own language inside of Go. Higher-order functions, functions that operate on other functions and return whole new functions, afford us the ability to compose or parameterize behaviors. The purpose of creating a DSL is to simplify the solutions to a class of problems by exposing to the DSL’s user a few concepts useful for solving those problems and empowering them configure and combine those concepts in meaningful ways. Composable dynamic behaviors created through higher-order programming are one way deliver that functionality. A More Useful Example

We’ll build on our work on hostnames to make something a little closer to what we might use in a real application. Importing the net/http package, let’s create another type identity:

1

type RequestFilter func(*http.Request) bool

We can use a RequestFilter in a simple HTTP server to evaluate whether a given http.Request satisfies a particular condition, as we did with HostFilter above. We can use those conditions to determine whether to handle or reject the request.

We’ll shift from working with hostnames as above to working with ranges of IP addresses. We’ll use CIDR blocks, e.g. "192.168.0.0/16", which identifies a range of IPs from 192.168.0.0 through 192.168.255.255. We’ll create a RequestFilter that filters requests based on IP.

From the net package, we’ll use the ParseCIDR function to parse the CIDRs, and the ParseIP function to parse IP addresses from incoming requests. One of the return values from ParseCIDR is an IPNet which conveniently has a Contains method that will do the work of telling us whether the incoming IP matches the range in our CIDR block.

So let’s also import the net package and write a RequestFilter that takes a variadic input of CIDR blocks in string form:

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18

func CIDR(cidrs ...string) RequestFilter { nets := make([]*net.IPNet, len(cidrs)) for i, cidr := range cidrs { // TODO: handle err _, nets[i], _ = net.ParseCIDR(cidr) } return func(r *http.Request) bool { // TODO: handle err host, _, _ := net.SplitHostPort(r.RemoteAddr) ip := net.ParseIP(host) for _, net := range nets { if net.Contains(ip) { return true } } return false } }

Note that the net/http package already contains a type for HTTP handlers, HandlerFunc:

1

type HandlerFunc func(ResponseWriter, *Request)

and we’ll be using higher-order functions and our RequestFilters to modify http.HandlerFuncs, so let’s declare a type for functions that operate on http.HandlerFuncs:

1

type Middleware func(http.HandlerFunc) http.HandlerFunc

and let’s make some functions to build Middleware that uses the RequestFilter:

1 2 3 4 5 6 7 8 9 10 11 12

func Allow(f RequestFilter) Middleware { return func(h http.HandlerFunc) http.HandlerFunc { return func(w http.ResponseWriter, r *http.Request) { if f(r) { h(w, r) } else { // TODO w.WriteHeader(http.StatusForbidden) } } } }

So now, for example, you could modify an HTTP handler MyHandler to only accept requests from 127.0.0.1 with something like:

1

filteredHandler := Allow(CIDR("127.0.0.1/32"))(MyHandler)

Let’s try it by running a simple server:

1 2 3 4 5 6 7 8

func hello(w http.ResponseWriter, r *http.Request) { fmt.Fprintf(w, "Hello\n") }

func main() { http.HandleFunc("/hello", Allow(CIDR("127.0.0.1/32")(hello)) log.Fatal(http.ListenAndServe(":1217", nil)) }

If you hit your new endpoint from your local machine at http://0.0.0.0:1217/hello, you should see “Hello” in response; if you hit it from another IP address, you should see a 403 Forbidden error.

For fun, let’s add another kind of RequestFilter that implements a really naive authentication mechanism:

1 2 3 4 5

func PasswordHeader(password string) RequestFilter { return func(r *http.Request) bool { return r.Header.Get("X-Password") == password } }

and one based on HTTP method:

1 2 3 4 5 6 7 8 9 10

func Method(methods ...string) RequestFilter { return func(r *http.Request) bool { for _, m := range methods { if r.Method == m { return true } } return false } }

and a Middleware that performs some simple logging:

1 2 3 4 5 6

func Logging(f http.HandlerFunc) http.HandlerFunc { return func(w http.ResponseWriter, r *http.Request) { fmt.Printf("[%v] - %s %s\n", time.Now(), r.Method, r.RequestURI) f(w, r) } }

which we can try with an update to our server:

1 2 3 4

func main() { http.HandleFunc("/hello", Logging(Allow(CIDR("127.0.0.1/32")(hello))) log.Fatal(http.ListenAndServe(":1217", nil)) }

Run this and visit http://localhost:1217/hello a few times in your browser and in the console where the server is running you should see:

1 2 3

[2016-12-14 07:42:12.022266374 -0500 EST] - GET /hello [2016-12-14 07:42:14.537985456 -0500 EST] - GET /hello [2016-12-14 07:42:24.220089221 -0500 EST] - GET /hello

This syntax is fairly declarative as is, but the method chaining can get a little awkward. Methods have to be chained in the right order to behave correctly, and the result can be difficult to read.

We can use a struct to further flesh out our DSL and give our users an even cleaner way to declare their middleware configuration:

1 2 3 4 5 6 7

type Filters []RequestFilters type Stack []Middleware type Endpoint struct { Handler http.HandlerFunc Allow Filters Middleware Stack }

then we could express the endpoint above with the same restrictions as:

1 2 3 4 5 6 7 8 9

var MyEndpoint = Endpoint{ Handler: hello, Allow: Filters{ CIDR("127.0.0.1/32"), }, Middleware: Stack{ Logging, }, }

Which is much easier to write, read, and modify. We just need to add a few methods to our struct and type identities turn this declarative description into a usable http.HandlerFunc:

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

// Combine creates a RequestFilter that is the conjunction // of all the RequestFilters in f. func (f Filters) Combine() RequestFilter { return func(r *http.Request) bool { for _, filter := range f { if !filter(r) { return false } } return true } }

// Apply returns an http.Handlerfunc that has had all of the // Middleware functions in s, if any, to f. func (s Stack) Apply(f http.HandlerFunc) http.HandlerFunc { g := f for _, middleware := range s { g = middleware(g) } return g }

// Builds the endpoint described by e, by applying // access restrictions and other middleware. func (e Endpoint) Build() http.HandlerFunc { allowFilter := e.Allow.Combine() restricted := Allow(allowFilter)(e.Handler)

return e.Middleware.Apply(restricted)

}

and, finally, modify the server to use the endpoint built this way:

1 2 3 4

func main() { http.HandleFunc("/hello", mw.MyEndpoint.Build()) log.Fatal(http.ListenAndServe(":1217", nil)) }

To see the benefit of this mini-DSL we’ve created, let’s add one more kind of middleware:

1 2 3 4 5 6 7 8

func SetHeader(key, value string) Middleware { return func(f http.HandlerFunc) http.HandlerFunc { return func(w http.ResponseWriter, r *RequestFilter) { w.Header().Set(key, value) f(w, r) } } }

And then add it, along with another RequestFilter, to our endpoint:

1 2 3 4 5 6 7 8 9 10 11 12

var MyEndpoint = Endpoint{ Handler: hello, Allow: Filters{ CIDR("127.0.0.1/32"), PasswordHeader("opensesame"), // added Method("GET"), // added }, Middleware: Stack{ Logging, SetHeader("X-Foo", "Bar"), // added }, }

We’ve added significantly to the complexity of MyEndpoint without adding much complexity to its declaration.

This is a useful DSL for building single HTTP endpoints, but frequently we’ll want more than just one on a service. We’ll add one last element to our demo DSL, a way to create several routes and their endpoints at once:

1 2 3 4 5 6 7 8 9 10

type Routes map[string]Endpoint

func (r Routes) Serve(addr string) error { mux := http.NewServeMux() for pattern, endpoint := range r { mux.Handle(pattern, endpoint.Build()) }

return http.ListenAndServe(addr, mux)

}

and then our service becomes:

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

func main() { routes := Routes{ "/hello": { Handler: hello, Middleware: Stack{ Logging, }, }, "/private": { Handler: hello, Allow: Filters{ CIDR("127.0.0.1/32"), PasswordHeader("opensesame"), }, Middleware: Stack{ Logging, }, }, "/test": { Handler: hello, Middleware: Stack{ Logging, SetHeader("X-Foo", "Bar"), }, }, } log.Fatal(routes.Serve(":1217")) }

Note that Go automatically infers the type of the Endpoint struct literals in the Routes map, saving us even more typing and clutter.

This HTTP middleware DSL shows how much can be accomplished in a relatively small amount of Go, but it’s a toy example. Here are some ideas for exercises to extend it and to make the DSL even more powerful:

Implement additional RequestFilters, like a rate-limiter, perhaps using golang.org/x/time/rate or juju/ratelimit, or a more robust authentication mechanism
Implement another Middleware
Modify the Endpoint struct to include a Deny field of type Filters, that rejects the request if any of its RequestFilters is true
Each of the endpoints in the final sample included Logging in its middleware; add to the DSL a facility to apply a set of common restrictions or middleware to all of the endpoints.
Create a way for this middleware stack to create a context.Context and to work with handlers that accept them.

To recap, we used type identities to create abstractions over simple collection types and functions of particular signatures, and we took advantage of Go syntax features like variadic functions and inferred types to write a smooth, uncluttered syntax. The heavy lifting in creating our DSL was performed by higher-order functions that let us create parameterized behaviors that could be combined and configured at runtime. We employed a few dangerous coding practices to do it, but as long as we apply them only when reducing complexity for end-users is the right tradeoff, we can all sleep at night.

The Go you get out of the box is detail-oriented, minimalistic, and can become verbose. Go gives you the tools, however, to build up your own abstractions- your own high-level language- to write code that is as pithy, elegant, and expressive as any you’ll find in a dynamic or purely functional language, but that still gives us access to all of the features we love about Go.

Back to top