{"id":13733968,"url":"https://github.com/aol/micro-server","last_synced_at":"2025-05-15T13:07:59.698Z","repository":{"id":27743972,"uuid":"31231846","full_name":"aol/micro-server","owner":"aol","description":"Microserver is a Java 8 native, zero configuration, standards based, battle hardened library to run Java Rest Microservices via a standard Java main class. Supporting pure Microservice or Micro-monolith styles.","archived":false,"fork":false,"pushed_at":"2023-03-21T11:09:09.000Z","size":8327,"stargazers_count":933,"open_issues_count":48,"forks_count":211,"subscribers_count":123,"default_branch":"master","last_synced_at":"2025-04-15T02:11:53.074Z","etag":null,"topics":["jersey","microservices","plugins","rest","spring","spring-boot"],"latest_commit_sha":null,"homepage":"http://micro-server.io/","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/aol.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2015-02-23T21:54:25.000Z","updated_at":"2025-04-07T23:23:04.000Z","dependencies_parsed_at":"2023-10-20T17:29:59.559Z","dependency_job_id":null,"html_url":"https://github.com/aol/micro-server","commit_stats":null,"previous_names":[],"tags_count":54,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aol%2Fmicro-server","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aol%2Fmicro-server/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aol%2Fmicro-server/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aol%2Fmicro-server/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aol","download_url":"https://codeload.github.com/aol/micro-server/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254346624,"owners_count":22055808,"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":["jersey","microservices","plugins","rest","spring","spring-boot"],"created_at":"2024-08-03T03:00:51.377Z","updated_at":"2025-05-15T13:07:54.686Z","avatar_url":"https://github.com/aol.png","language":"Java","readme":"\n# Microserver\n\n[![Build Status](https://travis-ci.org/aol/micro-server.svg)](https://travis-ci.org/aol/micro-server)\n[![Join the chat at https://gitter.im/aol/micro-server](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/aol/micro-server?utm_source=badge\u0026utm_medium=badge\u0026utm_campaign=pr-badge\u0026utm_content=badge)\n\nA convenient modular engine for Microservices. Microserver plugins offer seamless integration with Spring (core), Jersey, Guava, Tomcat, Grizzly, reactive programming, Hibernate (\u0026 Spring Data), Spring Boot, Codahale Metrics, Swagger and more to come!\n\n* [Microserver screencast : getting started with plugins](https://www.youtube.com/watch?v=sYn2cVTkfcM)\n\n![screen shot 2016-05-06 at 12 30 26 pm](https://cloud.githubusercontent.com/assets/9964792/15588807/8da91440-2387-11e6-979b-f24d456541f5.png)\n\n### Microserver plugins video\n[![Getting started video](https://cloud.githubusercontent.com/assets/9964792/6361863/9991c50c-bc7e-11e4-8d28-746b0b87b1da.png)](https://youtu.be/sYn2cVTkfcM)\n\n\n\n## Quick start\n\nInstall Microserver with Grizzly, Jackson and Jersey (Gradle config below)\n```groovy\n    compile group: 'com.oath.microservices', name:'micro-grizzly-with-jersey', version:'x.yz'\n```   \nInstall Microserver with Tomcat, Jackson and Jersey (Gradle config below)\n ```groovy\n    compile group: 'com.oath.microservices', name:'micro-tomcat-with-jersey', version:'x.yz'    \n ```\nCreate and run a simple app \n ```java\n    @Rest\n\t@Path(\"/test\")\n\tpublic class SimpleApp {\n\n\t\tpublic static void main(String[] args){\n\t\t\tnew MicroserverApp(()-\u003e\"test-app\").run();\n\t\t}\n\t\t@GET\n\t\tpublic String myEndPoint(){\n\t\t\treturn \"hello world!\";\n\t\t}\n    }\n```\n\nBrowse to *http://localhost:8080/test-app/test*\n\nSee the response  *hello world!*\n\nAdd plugins by adding them to your build file - rerun the app to get new end points, Spring beans and more!\n\n## Easy to use async NIO based REST\n\nReturn any reactive-streams Publisher from your REST end point to make them execute asynchronously automatically.\n\nE.g. Using Future from [cyclops-react](cyclops-react.io)\n\n```java\n   @GET\n   public Future\u003cString\u003e myEndPoint(){\n          return Future.of(()-\u003e{\n                                        sleep();\n                                        return \"hello world!\";\n                                        }, Executors.newFixedThreadPool(1));\n   }\n```\n\nWould be equivalent to the following code\n\n```java\n @GET\n public void myEndPoint(@Suspended AsyncResponse asyncResponse){\n      Future.of(()-\u003e{\n                                           sleep();\n                                           asyncResponse.resume(\"hello world!\");\n                                           return 1;\n\t\t}, Executors.newFixedThreadPool(1));\n}\n```\n\n# Why Microserver?\n\nMicroserver is a plugin engine for building Spring and Spring Boot based microservices. Microserver supports pure microservice and micro-monolith development styles. The micro-monolith style involves packaging multiple services into a single deployment - offering developers the productivity of microservice development without the operational risk. This can help teams adopt a Microservices architecture on projects that are currently monoliths.\n\nMicroserver plugins are orthogonal to Microservices. They solve a common problem in Microservice development whereby services are broken up and deployed separately but the code remains entangled in a monolithic common library. By making use of a plugin system that follows the same modular architectural principals as microservice development, teams can keep cross-service concerns and infrastructure in properly size, coherent and cohesive plugin modules.\n\n# Tutorial and overview\n\n[Tutorial](https://github.com/aol/micro-server/wiki/Getting-started-:-Tutorial) \n\n[Tutorial code](https://github.com/aol/micro-server/tree/master/micro-tutorial)\n\n## Note on Fat Jars\n\nMicroserver (\u0026 Cyclops) have a plugin architecture and make use of the Java Service Loader mechanism. Make sure your Fat Jar implementation is configured to aggregate services. With the Gradle Shadow Jar you do this with\n ```groovy\n    shadowJar {\n      mergeServiceFiles()\n    }\n ```\n\n\n### Quick start youtube video\n\n[![Getting started video](https://cloud.githubusercontent.com/assets/9964792/6361863/9991c50c-bc7e-11e4-8d28-746b0b87b1da.png)](https://www.youtube.com/watch?v=McXy9oGRpfA\u0026feature=youtu.be)\n\n\nNote the main launch class has been changed from MicroServerStartup to MicroserverApp\n\n## Blurb\n\nMicroserver is a zero configuration, standards based, battle hardened library to run Java Rest Microservices via a standard Java main class. It has been used in production in AOL since July 2014.\n\n\n## Get Microserver\n\n\n![Build health](https://travis-ci.org/aol/micro-server.svg)\n\n* micro-grizzly-with-jersey\n[![Maven Central](https://maven-badges.herokuapp.com/maven-central/com.oath.microservices/micro-grizzly-with-jersey/badge.svg)](https://maven-badges.herokuapp.com/maven-central/com.oath.microservices/micro-grizzly-with-jersey)\n* micro-tomcat-with-jersey\n[![Maven Central](https://maven-badges.herokuapp.com/maven-central/com.oath.microservices/micro-tomcat-with-jersey/badge.svg)](https://maven-badges.herokuapp.com/maven-central/com.oath.microservices/micro-tomcat-with-jersey)\n* micro-core \n[![Maven Central](https://maven-badges.herokuapp.com/maven-central/com.oath.microservices/micro-core/badge.svg)](https://maven-badges.herokuapp.com/maven-central/com.oath.microservices/micro-core)\n* micro-boot  : Microserver driving Spring Boot\n[![Maven Central](https://maven-badges.herokuapp.com/maven-central/com.oath.microservices/micro-boot/badge.svg)](https://maven-badges.herokuapp.com/maven-central/com.oath.microservices/micro-boot)\n* micro-spring-boot  : Spring Boot driving Microserver\n[![Maven Central](https://maven-badges.herokuapp.com/maven-central/com.oath.microservices/micro-spring-boot/badge.svg)](https://maven-badges.herokuapp.com/maven-central/com.oath.microservices/micro-spring-boot)\n\n\n## Info\n\n[wiki](https://github.com/aol/micro-server/wiki)\n\n[Google Group](https://groups.google.com/forum/#!forum/micro-server)\n\n[Example Apps : Microserver Core with Grizzly and Jersey](https://github.com/aol/micro-server/tree/master/micro-grizzly/src/test/java/app)\n\n[Example Apps : Microserver Boot](https://github.com/aol/micro-server/tree/master/micro-boot/src/test/java/app)\n\n[Java Doc : Microserver Core](http://www.javadoc.io/doc/com.oath.microservices/micro-core/0.62)\n\n[Java Doc : Microserver Boot](http://www.javadoc.io/doc/com.oath.microservices/micro-core/0.62)\n\n\n\n### Maven dependency\n\nMicroserver Grizzly with Jersey\n ```xml\n    \u003cdependency\u003e\n      \u003cgroupId\u003ecom.oath.microservices\u003c/groupId\u003e\n      \u003cartifactId\u003emicro-grizzly-with-jersey\u003c/artifactId\u003e\n      \u003cversion\u003ex.yz\u003c/version\u003e\n    \u003c/dependency\u003e\n```\nMicroserver Spring Boot \n ```xml\n    \u003cdependency\u003e\n      \u003cgroupId\u003ecom.oath.microservices\u003c/groupId\u003e\n      \u003cartifactId\u003emicro-spring-boot\u003c/artifactId\u003e\n      \u003cversion\u003ex.yz\u003c/version\u003e\n    \u003c/dependency\u003e\n ```\n\n\n### Gradle dependency\n\nMicroserver core \n ```groovy\t\n\t compile group: 'com.oath.microservices', name:'micro-core', version:'x.yz'\n ```\t \nMicroserver Spring Boot \n ```groovy\t \n\t  compile group: 'com.oath.microservices', name:'micro-spring-boot', version:'x.yz'\n ```\n## Tech Stack\n\nMicroserver core is a lightweight server configuration engine built using Spring, Cyclops and Jackson.\n\n\n\n## Zero Configuration\n\nNo directory structure is imposed by the server and no XML is required. There is no framework config. Just a jar file and your application. You can, of course, configure your application without limit.\n\nExample working application :-\n\n### The main class :-\n\n```java   \n     public class AppRunnerTest {\n\n\t\t\n\t\tpublic static void main(String[] args) throws InterruptedException {\n\t\t\tnew MicroserverApp(() -\u003e \"test-app\").run();\n\t\t}\n\n    }\n ```\n\nThis will deploy a REST server on port 8080 (configurable by test-app.port in application.properties), it will also automagically capture any Rest end points (Spring \u0026 Jersey annotations) that implement the tag interface RestResource (see below for an example).\n\n### A rest end point\n\n```java\n@Rest\n@Path(\"/status\")\npublic class StatusResource {\n\n    @GET\n    @Produces(\"text/plain\")\n    @Path(\"/ping\")\n    public String ping() {\n        return \"ok\";\n    }\n\n}\n```\n### Configuration Options\n\nIf you find you need configuration options for your application you have two options.\n\n1. Override some of the available options on the Module interface (ConfigurableModule provides a builder mechanism for this)\n2. [Implement a custom plugin](https://github.com/aol/micro-server/wiki/Creating-a-Microserver-plugin) (the cleanest option, which also promotes reuse across services).\n\n### Application configuration (for Grizzly with Jersey)\n\nThe core of Microserver is a Spring 4.x Dependency Injection container which is used to store all the main classes of your Microservice (s). The Spring Dependency Injection container can be configured by the @Microservice Annotation on your main class, or by the Config object (optionally passed as a parameter to startup).\n\n### Micro-monolith Architectural Overview\n\nEach Microservice is a Jersey REST Application, these can be deployed independently as pure Microservices or together as a micro-monolith. Multiple Microservices can run on the same server, by adding them to the classpath at runtime. They share a common Spring Dependency Injection container (as they are smaller services, we feel it makes sense to share resources such as ThreadPools, Datasources etc), but act as totally separate Rest applications. \n\nWhen creating embedded Microservices (multiple services colocated on the same JVM and Spring container), the development project should be independent, but the colocated instances should be tested as they will be deployed in production. There will be more info to follow on the wiki, on how and why we have implemented and scaled this pattern (the goal is to achieve both the benefits of a full Microservice architecture, but minimise the costs as articulated by Robert (Uncle Bob) C. Martin and others - e.g. [here: Microservices and Jars](http://blog.cleancoder.com/uncle-bob/2014/09/19/MicroServicesAndJars.html) .\n\nJersey REST Applications are configured by the Module interface (at least one of which must be specified on startup).\n\n![high level architecture](https://cloud.githubusercontent.com/assets/9964792/6375067/a6e4f65a-bd0c-11e4-85dc-82ae0d95d44b.png)\n\n\n#### Rest configuration\n\nThe configuration of your Rest endpoints can be managed via the Module interface. The Module interface has a number of Java 8 default methods and a single abstract method (getContext).  It behaves as a functional interface, and can be defined by a lambda expression. When used in this way the lambda represents the context the Microserver will create Rest end points on.\n\ne.g. \n\n ```java\n    new MicroserverApp(() -\u003e \"context\").start();\n ```\n\n() -\u003e \"context\"  is a Module!\n\n\n#### Configurable Options\n\nModule provides the following default methods, that clients can override\n\n ```java\n    default Map\u003cString,String\u003e getPropertyOverrides(){\n\t\treturn Maps.newHashMap();\n\t}\n\tdefault Set\u003cClass\u003e getSpringConfigurationClasses(){\n\t\treturn Sets.newHashSet(Classes.CORE_CLASSES.getClasses());\n\t}\n\tdefault List\u003cClass\u003e getRestResourceClasses() {\n\t\treturn Arrays.asList(RestResource.class);\n\t}\n\tdefault List\u003cClass\u003e getRestAnnotationClasses() {\n\t\treturn Arrays.asList(Rest.class);\n\t}\n\t\n\tdefault List\u003cString\u003e getDefaultJaxRsPackages(){\n\t\treturn Arrays.asList(\"com.wordnik.swagger.sample.resource\",\n\t\t\t\t\"com.wordnik.swagger.sample.util\"\t);\n\t}\n\t\n\tdefault List\u003cClass\u003e getDefaultResources(){\n\t\treturn Arrays.asList(JacksonFeature.class, \n\t\t\t\t//SWAGGER CLASSES\n\t\t\t\tApiListingResourceJSON.class,JerseyApiDeclarationProvider.class,\n\t\t\t\tJerseyResourceListingProvider.class);\n\t}\n\t\n\tdefault List\u003cServletContextListener\u003e getListeners(ServerData data){\n\t\treturn ImmutableList.of(new ContextLoaderListener(data\n\t\t\t\t.getRootContext()),\n\t\t\t\tnew JerseySpringIntegrationContextListener(data),\n\t\t\t\tnew SwaggerInitializer(data));\n\t}\n\tdefault Map\u003cString,Filter\u003e getFilters(ServerData data) {\n\t\treturn ImmutableMap.of(\"/*\",new QueryIPRetriever());\n\t}\n\tdefault Map\u003cString,Servlet\u003e getServlets(ServerData data) {\n\t\treturn ImmutableMap.of();\n\t}\n\t\n\tdefault  String getJaxWsRsApplication(){\n\t\treturn JerseyRestApplication.class.getCanonicalName();\n\t}\n\tdefault String getProviders(){\n\t\treturn \"com.aol.micro.server.rest.providers\";\n\t}\n ```\nRestResource class defines the tag interface used to identify Rest end points for this module.\n\nFilters provides a map of Servlet filters and the paths to which they should be applied\n\nProviders allows client code to change the Jersey Providers packages\n\nJaxWsRsApplication allows client code to completely override the Microserver jax.ws.rs.Application\n\n#### Property file configuration\n\nMicroserver supports auto-discovery of application.properties. Microserver will assume a default file name of 'application.properties'.  Microserver will check for a properties in the following order\n\n1. System property 'application.property.file' and if present will load the property file from disk using that. \n\n2. Otherwise, Microserver will look for a System Property 'application.env' and will load the application property file from the classpath using the resource name 'application-${application.env}.properties. \n\n3. Alternatively, Microserver will load application.properties directly from the classpath.\n\n4. If still not found Microserver will load application.properties from disk in the current directory\n\nThe default file name application.properties can be configured by exception (use PropertyFileConfig.setApplicationPropertyFileName(String filename).\n\nMicroserver application properties loading is configured by the class PropertyFileConfig. You can replace this with your own Spring configuration file to load property files by a different set of rules (by passing in your class to the constructor of Microserver).\n\n## Embed and colocate Microservices\n\nMicroserver supports the embedding of multiple microservices within a single Microserver, this is not the default mode of operation and involves a little more work to setup. All Microservices will share a single Spring context, so some care needs to be taken when authoring such Microservices to avoid conflicts. This does mean that they can share resources (such as database connections) where it makes sense to do so.\n\nEmbedded microservices should be collated at '''runtime only'''. There should be no compile time dependency between embedded microservices (otherwise you are not building microservices but a monolithic application).\n\nEmbedding microservices is an optimisation that allows better performance, enhanced robustness and reliability and easier management  of microservices - while still maintaining the advantages of horizontal scalability offered by the microservices approach.\n\n### Embedded Microservices example\n\nThis example will start two different Rest endpoints - one on context \"test-app\" and another on context \"alternative-app\".\n\"test-app\" will automagically wire in any Jersey endpoints that implement TestAppRestResource.\n\"alternative-app\" will automagically wire in any Jersey endpoints that implement AltAppRestResource.\n ```java\n\t@Microserver\n\tpublic class EmbeddedAppRunnerTest {\n\t\n\t\tpublic static void main(String[] args) throws InterruptedException {\n\t\t\tnew MicroserverApp(EmbeddedAppRunnerTest.class, \n\t\t\t\t\tnew EmbeddedModule(TestAppRestResource.class,\"test-app\"),\n\t\t\t\t\tnew EmbeddedModule(AltAppRestResource.class,\"alternative-app\")).start();\n\t\t\n\t\t\t\n\t\t\n\t\t}\n\t}\n\n ```\n\n\n## Building a 'fat' Jar\n\nWe recommend the Gradle plugin Shadow Jar. For Gradle 2.0 simply define it in your plugins section -\u003e\n ```groovy\nplugins {\n  id 'java' // or 'groovy' Must be explicitly applied\n  id 'com.github.johnrengelman.shadow' version '1.2.0'\n}\n ```\nMaven users can use Shade plugin or equivalent (Maven assembly plugin).\n \n# Thanks to our Sponsors\n\n* ![YourKit Logo](https://www.yourkit.com/images/yklogo.png) YourKit supports open source projects with innovative and intelligent tools\nfor monitoring and profiling Java and .NET applications.\nYourKit is the creator of \u003ca href=\"https://www.yourkit.com/java/profiler/\"\u003eYourKit Java Profiler\u003c/a\u003e,\n\u003ca href=\"https://www.yourkit.com/.net/profiler/\"\u003eYourKit .NET Profiler\u003c/a\u003e,\nand \u003ca href=\"https://www.yourkit.com/youmonitor/\"\u003eYourKit YouMonitor\u003c/a\u003e.\n","funding_links":[],"categories":["Projects","I. Development","Java","微服务库","项目","REST Frameworks","Frameworks / Runtimes"],"sub_categories":["REST Frameworks","1. Common frameworks and libraries","REST框架"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faol%2Fmicro-server","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faol%2Fmicro-server","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faol%2Fmicro-server/lists"}