{"id":13524324,"url":"https://github.com/hexagontk/hexagon","last_synced_at":"2026-01-19T23:06:23.495Z","repository":{"id":39633106,"uuid":"56139239","full_name":"hexagontk/hexagon","owner":"hexagontk","description":"Hexagon is a microservices toolkit written in Kotlin. Its purpose is to ease the building of services (Web applications or APIs) that run inside a cloud platform.","archived":false,"fork":false,"pushed_at":"2025-04-27T18:05:33.000Z","size":116976,"stargazers_count":591,"open_issues_count":3,"forks_count":97,"subscribers_count":24,"default_branch":"main","last_synced_at":"2025-05-07T18:08:42.085Z","etag":null,"topics":["framework","gradle","hexagonal-architecture","http","http-server","jvm","kotlin","micro-framework","microservices","pebble-templates","rest","server","toolkit","web"],"latest_commit_sha":null,"homepage":"https://hexagontk.com","language":"Kotlin","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hexagontk.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"contributing.md","funding":null,"license":"license.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"github":["hexagontk"]}},"created_at":"2016-04-13T09:35:34.000Z","updated_at":"2025-04-11T17:51:40.000Z","dependencies_parsed_at":"2023-09-24T15:25:42.322Z","dependency_job_id":"58e70af7-eb54-4ada-a609-99f6becf6ed2","html_url":"https://github.com/hexagontk/hexagon","commit_stats":{"total_commits":4279,"total_committers":42,"mean_commits":"101.88095238095238","dds":"0.055854171535405506","last_synced_commit":"7436f1985832d21696fe7c08a0f454add6520284"},"previous_names":["hexagontk/hexagon","hexagonkt/hexagon"],"tags_count":351,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hexagontk%2Fhexagon","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hexagontk%2Fhexagon/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hexagontk%2Fhexagon/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hexagontk%2Fhexagon/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hexagontk","download_url":"https://codeload.github.com/hexagontk/hexagon/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253505643,"owners_count":21918940,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["framework","gradle","hexagonal-architecture","http","http-server","jvm","kotlin","micro-framework","microservices","pebble-templates","rest","server","toolkit","web"],"created_at":"2024-08-01T06:01:08.991Z","updated_at":"2025-11-17T05:01:17.486Z","avatar_url":"https://github.com/hexagontk.png","language":"Kotlin","funding_links":["https://github.com/sponsors/hexagontk"],"categories":["开源库和框架"],"sub_categories":["Web 开发"],"readme":"\n\u003ch3 align=\"center\"\u003e\n  \u003ca href=\"https://hexagontk.com\"\u003e\n    \u003cimg alt=\"Hexagon\" src=\"https://hexagontk.com/stable/icon-small.png\" /\u003e\n  \u003c/a\u003e\n  \u003cbr\u003e\n  Hexagon\n\u003c/h3\u003e\n\n\u003ch4 align=\"center\"\u003eThe atoms of your platform\u003c/h4\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/hexagontk/hexagon/actions\"\u003e\n    \u003cimg\n      alt=\"GitHub Actions\"\n      src=\"https://github.com/hexagontk/hexagon/actions/workflows/release.yml/badge.svg\" /\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://hexagontk.com/stable/jacoco\"\u003e\n    \u003cimg src=\"https://hexagontk.com/stable/img/coverage.svg\" alt=\"Coverage\" /\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://search.maven.org/search?q=g:com.hexagontk\"\u003e\n    \u003cimg src=\"https://hexagontk.com/stable/img/download.svg\" alt=\"Maven Central Repository\" /\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://hexagontk.com\"\u003eHome Site\u003c/a\u003e |\n  \u003ca href=\"https://hexagontk.com/stable/quick_start\"\u003eQuick Start\u003c/a\u003e\n\u003c/p\u003e\n\n---\n\n## What is Hexagon\n\nHexagon is a microservices' toolkit (not a [framework]) written in [Kotlin]. Its purpose is to ease\nthe building of server applications (Web applications, APIs or Serverless handlers) that run inside\na cloud platform.\n\nThe Hexagon Toolkit provides several libraries to build server applications. These libraries provide\nsingle standalone features and are referred to as [\"Ports\"][Ports and Adapters Architecture].\n\nThe main ports are:\n\n* [The HTTP server]: supports HTTPS, HTTP/2, WebSockets, mutual TLS, static files (serve and\n  upload), forms processing, cookies, CORS and more.\n* [The HTTP client]: which supports mutual TLS, HTTP/2, WebSockets, cookies, form fields and files\n  among other features.\n* [Serialization]: provides a common way of using different data formats. Data formats are pluggable\n  and are handled in the same way regardless of their library.\n* [Template Processing]: allows template processing from URLs (local files, resources or HTTP\n  content) binding name patterns to different engines.\n\nEach of these features or ports may have different implementations called\n[\"Adapters\"][Ports and Adapters Architecture].\n\nHexagon is designed to fit in applications that conform to the [Hexagonal Architecture] (also called\n[Clean Architecture] or [Ports and Adapters Architecture]). Also, its design principles also fits in\nthis architecture.\n\nThe Hexagon's goals and design principles are:\n\n* **Put you in Charge**: There is no code generation, no runtime annotation processing, no classpath\n  based logic, and no implicit behaviour. You control your tools, not the other way around.\n\n* **Modular**: Each feature (Port) or adapter is isolated in its own module. Use only the modules\n  you need without carrying unneeded dependencies.\n\n* **Pluggable Adapters**: Every Port may have many implementations (Adapters) using different\n  technologies. You can swap adapters without changing the application code.\n\n* **Batteries Included**: It contains all the required pieces to make production-grade applications:\n  logging utilities, serialization, resource handling and build helpers.\n\n* **Native Image**: most of the toolkit libraries include GraalVM metadata (check the [libraries\n  catalog]), native tests are run on CI to ensure native images can be built out of the box.\n\n* **Properly Tested**: The project's coverage is checked in every Pull Request. It is also\n  stress-tested at [TechEmpower Frameworks Benchmark][benchmark].\n\nFor more information check the [Quick Start Guide].\n\n[framework]: https://stackoverflow.com/a/3057818/973418\n[Kotlin]: http://kotlinlang.org\n[The HTTP server]: http://hexagontk.com/http_server\n[The HTTP client]: http://hexagontk.com/http_client\n[Serialization]: http://hexagontk.com/serialization\n[Template Processing]: http://hexagontk.com/templates\n[Hexagonal Architecture]: http://fideloper.com/hexagonal-architecture\n[Clean Architecture]: https://8thlight.com/blog/uncle-bob/2012/08/13/the-clean-architecture.html\n[Ports and Adapters Architecture]: https://herbertograca.com/2017/09/14/ports-adapters-architecture\n[Quick Start Guide]: http://hexagontk.com/quick_start\n[libraries catalog]: https://www.graalvm.org/native-image/libraries-and-frameworks\n\n## Simple HTTP service\n\nYou can clone a starter project ([Gradle Starter] or [Maven Starter]). Or you can create a project\nfrom scratch following these steps:\n\n1. Configure Kotlin in [Gradle][Setup Gradle] or [Maven][Setup Maven].\n2. Add the dependency:\n\n  * In Gradle. Import it inside `build.gradle`:\n\n    ```groovy\n    repositories {\n        mavenCentral()\n    }\n\n    implementation(\"com.hexagontk.http:http_server_jetty:$hexagonVersion\")\n    ```\n\n  * In Maven. Declare the dependency in `pom.xml`:\n\n    ```xml\n    \u003cdependency\u003e\n      \u003cgroupId\u003ecom.hexagontk.http\u003c/groupId\u003e\n      \u003cartifactId\u003ehttp_server_jetty\u003c/artifactId\u003e\n      \u003cversion\u003e$hexagonVersion\u003c/version\u003e\n    \u003c/dependency\u003e\n    ```\n\n3. Write the code in the `src/main/kotlin/Hello.kt` file:\n\n```kotlin\n// hello_world\nimport com.hexagontk.core.media.TEXT_PLAIN\nimport com.hexagontk.http.model.ContentType\nimport com.hexagontk.http.server.HttpServer\nimport com.hexagontk.http.server.HttpServerSettings\nimport com.hexagontk.http.server.serve\n\nlateinit var server: HttpServer\n\n/**\n * Start a Hello World server, serving at path \"/hello\".\n */\nfun main() {\n    server = serve(JettyServletHttpServer(), HttpServerSettings(bindPort = 0)) {\n        get(\"/hello/{name}\") {\n            val name = pathParameters[\"name\"]\n            ok(\"Hello $name!\", contentType = ContentType(TEXT_PLAIN))\n        }\n    }\n    println(\"Try it at http://localhost:${server.runtimePort}/hello/World\")\n}\n// hello_world\n```\n\n4. Run the service and view the results at: [http://localhost:2010/hello][Endpoint]\n\n[Gradle Starter]: https://github.com/hexagontk/gradle_starter\n[Maven Starter]: https://github.com/hexagontk/maven_starter\n[Setup Gradle]: https://kotlinlang.org/docs/reference/using-gradle.html\n[Setup Maven]: https://kotlinlang.org/docs/reference/using-maven.html\n[Endpoint]: http://localhost:2010/hello\n\n## Examples\n\n\u003cdetails\u003e\n\u003csummary\u003eBooks Example\u003c/summary\u003e\n\nA simple CRUD example showing how to manage book resources. Here you can check the\n[full test](http_test/main/examples/BooksTest.kt).\n\n```kotlin\n// books\ndata class Book(val author: String, val title: String)\n\nprivate val books: MutableMap\u003cInt, Book\u003e = linkedMapOf(\n    100 to Book(\"Miguel de Cervantes\", \"Don Quixote\"),\n    101 to Book(\"William Shakespeare\", \"Hamlet\"),\n    102 to Book(\"Homer\", \"The Odyssey\")\n)\n\nprivate val path: PathHandler = path {\n\n    post(\"/books\") {\n        val author = queryParameters[\"author\"]?.text ?: return@post badRequest(\"Missing author\")\n        val title = queryParameters[\"title\"]?.text ?: return@post badRequest(\"Missing title\")\n        val id = (books.keys.maxOrNull() ?: 0) + 1\n        books += id to Book(author, title)\n        created(id.toString())\n    }\n\n    get(\"/books/{id}\") {\n        val bookId = pathParameters.require(\"id\").toInt()\n        val book = books[bookId]\n        if (book != null)\n            ok(\"Title: ${book.title}, Author: ${book.author}\")\n        else\n            notFound(\"Book not found\")\n    }\n\n    put(\"/books/{id}\") {\n        val bookId = pathParameters.require(\"id\").toInt()\n        val book = books[bookId]\n        if (book != null) {\n            books += bookId to book.copy(\n                author = queryParameters[\"author\"]?.text ?: book.author,\n                title = queryParameters[\"title\"]?.text ?: book.title\n            )\n\n            ok(\"Book with id '$bookId' updated\")\n        }\n        else {\n            notFound(\"Book not found\")\n        }\n    }\n\n    delete(\"/books/{id}\") {\n        val bookId = pathParameters.require(\"id\").toInt()\n        val book = books[bookId]\n        books -= bookId\n        if (book != null)\n            ok(\"Book with id '$bookId' deleted\")\n        else\n            notFound(\"Book not found\")\n    }\n\n    // Matches path's requests with *any* HTTP method as a fallback (return 405 instead 404)\n    after(ALL - DELETE - PUT - GET, \"/books/{id}\") {\n        send(METHOD_NOT_ALLOWED_405)\n    }\n\n    get(\"/books\") {\n        ok(books.keys.joinToString(\" \", transform = Int::toString))\n    }\n}\n// books\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eError Handling Example\u003c/summary\u003e\n\nCode to show how to handle callback exceptions and HTTP error codes. Here you can check the\n[full test](http_test/main/examples/ErrorsTest.kt).\n\n```kotlin\n// errors\nclass CustomException : IllegalArgumentException()\n\nprivate val path: PathHandler = path {\n\n    /*\n     * Catching `Exception` handles any unhandled exception, has to be the last executed (first\n     * declared)\n     */\n    exception\u003cException\u003e {\n        internalServerError(\"Root handler\")\n    }\n\n    exception\u003cIllegalArgumentException\u003e {\n        val error = exception?.message ?: exception?.javaClass?.name ?: fail\n        val newHeaders = response.headers + Header(\"runtime-error\", error)\n        send(598, \"Runtime\", headers = newHeaders)\n    }\n\n    exception\u003cUnsupportedOperationException\u003e {\n        val error = exception?.message ?: exception?.javaClass?.name ?: fail\n        val newHeaders = response.headers + Header(\"error\", error)\n        send(599, \"Unsupported\", headers = newHeaders)\n    }\n\n    get(\"/exception\") { throw UnsupportedOperationException(\"error message\") }\n    get(\"/baseException\") { throw CustomException() }\n    get(\"/unhandledException\") { error(\"error message\") }\n    get(\"/invalidBody\") { ok(LocalDateTime.now()) }\n\n    get(\"/halt\") { internalServerError(\"halted\") }\n    get(\"/588\") { send(588) }\n\n    // It is possible to execute a handler upon a given status code before returning\n    before(pattern = \"*\", status = 588) {\n        send(578, \"588 -\u003e 578\")\n    }\n}\n// errors\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eFilters Example\u003c/summary\u003e\n\nThis example shows how to add filters before and after route execution. Here you can check the\n[full test](http_test/main/examples/FiltersTest.kt).\n\n```kotlin\n// filters\nprivate val users: Map\u003cString, String\u003e = mapOf(\n    \"Turing\" to \"London\",\n    \"Dijkstra\" to \"Rotterdam\"\n)\n\nprivate val path: PathHandler = path {\n    filter(\"*\") {\n        val start = System.nanoTime()\n        // Call next and store result to chain it\n        val next = next()\n        val time = (System.nanoTime() - start).toString()\n        // Copies result from chain with the extra data\n        next.send(headers = response.headers + Header(\"time\", time))\n    }\n\n    filter(\"/protected/*\") {\n        val authorization = request.authorization ?: return@filter unauthorized(\"Unauthorized\")\n        val credentials = authorization.body\n        val userPassword = String(credentials.decodeBase64()).split(\":\")\n\n        // Parameters set in call attributes are accessible in other filters and routes\n        send(attributes = attributes\n          + (\"username\" to userPassword[0])\n          + (\"password\" to userPassword[1])\n        ).next()\n    }\n\n    // All matching filters are run in order unless call is halted\n    filter(\"/protected/*\") {\n        if(users[attributes[\"username\"]] != attributes[\"password\"])\n            send(FORBIDDEN_403, \"Forbidden\")\n        else\n            next()\n    }\n\n    get(\"/protected/hi\") {\n        ok(\"Hello ${attributes[\"username\"]}!\")\n    }\n\n    path(\"/after\") {\n        after(PUT) {\n            send(ALREADY_REPORTED_208)\n        }\n\n        after(PUT, \"/second\") {\n            send(NO_CONTENT_204)\n        }\n\n        after(\"/second\") {\n            send(CREATED_201)\n        }\n\n        after {\n            send(ACCEPTED_202)\n        }\n    }\n}\n// filters\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eFiles Example\u003c/summary\u003e\n\nThe following code shows how to serve resources. Here you can check the\n[full test](http_test/main/examples/FilesTest.kt).\n\n```kotlin\n// files\nprivate val path: PathHandler = path {\n\n    // Serve `public` resources folder on `/*`\n    after(\n        methods = setOf(GET),\n        pattern = \"/*\",\n        status = NOT_FOUND_404,\n        callback = UrlCallback(urlOf(\"classpath:public\"))\n    )\n\n    path(\"/static\") {\n        get(\"/files/*\", UrlCallback(urlOf(\"classpath:assets\")))\n        get(\"/resources/*\", FileCallback(File(directory)))\n    }\n\n    get(\"/html/*\", UrlCallback(urlOf(\"classpath:assets\"))) // Serve `assets` files on `/html/*`\n    get(\"/pub/*\", FileCallback(File(directory))) // Serve `test` folder on `/pub/*`\n}\n// files\n```\n\u003c/details\u003e\n\u003cdetails\u003e\n\u003csummary\u003eMultipart Example\u003c/summary\u003e\n\nThe following code shows how to receive files. Here you can check the\n[full test](http_test/main/examples/FilesTest.kt).\n\n```kotlin\n// multipart\nprivate val path: PathHandler = path {\n\n    // Serve `public` resources folder on `/*`\n    post(\"/multipart\") {\n        val headers = parts.first().let { p -\u003e\n            val name = p.name\n            val bodyString = p.bodyString()\n            val size = p.size.toString()\n            Headers(\n                Header(\"name\", name),\n                Header(\"body\", bodyString),\n                Header(\"size\", size),\n            )\n        }\n\n        ok(headers = headers)\n    }\n\n    post(\"/file\") {\n        val part = parts.first()\n        val content = part.bodyString()\n        val submittedFile = part.submittedFileName ?: \"\"\n        ok(content, headers = response.headers + Header(\"submitted-file\", submittedFile))\n    }\n\n    post(\"/form\") {\n        fun serializeMap(map: Parameters): List\u003cString\u003e = listOf(\n            map.all.entries.joinToString(\"\\n\") { (k, v) -\u003e\n                \"$k:${v.joinToString(\",\") { it.text }}\"\n            }\n        )\n\n        val queryParams = serializeMap(queryParameters).map { Parameter(\"query-params\", it) }\n        val formParams = serializeMap(formParameters).map { Parameter(\"form-params\", it) }\n\n        ok(headers = response.headers + Headers(queryParams) + Headers(formParams))\n    }\n}\n// multipart\n```\n\u003c/details\u003e\n\nYou can check more sample projects and snippets at the [examples page].\n\n[examples page]: https://hexagontk.com/examples/example_projects\n\n## Status\n\nThe toolkit is properly tested. This is the coverage report:\n\n[![Coverage]][CoverageReport]\n\nPerformance is not the primary goal, but it is taken seriously. You can check performance numbers\nin the [TechEmpower Web Framework Benchmarks][benchmark].\n\n[Coverage]: https://hexagontk.com/stable/img/coverage.svg\n[CoverageReport]: https://hexagontk.com/stable/jacoco\n[benchmark]: https://www.techempower.com/benchmarks\n\n## Contribute\n\nIf you like this project and want to support it, the easiest way is to [give it a star] :v:.\n\nIf you feel like you can do more. You can contribute to the project in different ways:\n\n* By using it and [spreading the word][@hexagontk].\n* Giving feedback by [X (Twitter)][@hexagontk].\n* Requesting [new features or submitting bugs][issues].\n* Voting for the features you want in the [issue tracker][issues] (using [reactions]).\n* And... Drum roll... Submitting [code or documentation][contributing].\n\nTo know what issues are currently open and be aware of the next features you can check the\n[Organization Board] at GitHub.\n\nYou can ask any question, suggestion or complaint at the project's [discussions]. You can\nbe up-to-date of project's news following [@hexagontk] on X (Twitter).\n\nThanks to all project's [contributors]!\n\n[give it a star]: https://github.com/hexagontk/hexagon/stargazers\n[discussions]: https://github.com/hexagontk/hexagon/discussions/categories/q-a\n[@hexagontk]: https://twitter.com/hexagontk\n[issues]: https://github.com/hexagontk/hexagon/issues\n[reactions]: https://github.com/blog/2119-add-reactions-to-pull-requests-issues-and-comments\n[contributing]: https://github.com/hexagontk/hexagon/contribute\n[Organization Board]: https://github.com/orgs/hexagontk/projects/2\n[contributors]: https://github.com/hexagontk/hexagon/graphs/contributors\n\n## License\n\nThe project is licensed under the [MIT License]. This license lets you use the source for free or\ncommercial purposes as long as you provide attribution and don’t hold any project member liable.\n\n[MIT License]: license.md\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhexagontk%2Fhexagon","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhexagontk%2Fhexagon","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhexagontk%2Fhexagon/lists"}