{"id":13694520,"url":"https://github.com/xmolecules/jmolecules","last_synced_at":"2026-01-11T17:48:20.207Z","repository":{"id":38453754,"uuid":"237967443","full_name":"xmolecules/jmolecules","owner":"xmolecules","description":"Libraries to help developers express architectural abstractions in Java code","archived":false,"fork":false,"pushed_at":"2025-03-06T09:18:34.000Z","size":405,"stargazers_count":1325,"open_issues_count":21,"forks_count":106,"subscribers_count":55,"default_branch":"main","last_synced_at":"2025-04-03T13:51:22.601Z","etag":null,"topics":["architecture","domain-driven-design","java"],"latest_commit_sha":null,"homepage":"http://jmolecules.org","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/xmolecules.png","metadata":{"files":{"readme":"readme.adoc","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","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}},"created_at":"2020-02-03T13:08:24.000Z","updated_at":"2025-04-03T09:02:10.000Z","dependencies_parsed_at":"2023-02-10T10:01:21.936Z","dependency_job_id":"31c89776-5844-4f8c-a14b-20d1929f4916","html_url":"https://github.com/xmolecules/jmolecules","commit_stats":{"total_commits":121,"total_committers":17,"mean_commits":7.117647058823529,"dds":0.4380165289256198,"last_synced_commit":"e85583dc2f631ef8df0e53fa2a3d29e08f6c530f"},"previous_names":["odrotbohm/jddd"],"tags_count":13,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xmolecules%2Fjmolecules","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xmolecules%2Fjmolecules/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xmolecules%2Fjmolecules/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xmolecules%2Fjmolecules/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/xmolecules","download_url":"https://codeload.github.com/xmolecules/jmolecules/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248309666,"owners_count":21082255,"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":["architecture","domain-driven-design","java"],"created_at":"2024-08-02T17:01:34.061Z","updated_at":"2026-01-11T17:48:20.150Z","avatar_url":"https://github.com/xmolecules.png","language":"Java","readme":":toc:\n\n= jMolecules – Architectural abstractions for Java\n\nA set of libraries to help developers implement domain models in distraction-free, plain old Java.\n\n== Ideas behind jMolecules\n\n- Explicitly express architectural concepts for easier code reading and writing.\n- Keep domain-specific code free from technical dependencies. Reduce boilerplate code.\n- Automatically generate documentation and validate implementation structures and your architecture.\n\n== Goals\n\n1. Make developers life easier.\n2. Express that a piece of code (a package, class, or method) implements an architectural concept.\n3. Make it easy for the human reader to determine what kind of architectural concepts a given piece of code is.\n4. Allow tool integration:\n  a. Augmentation of the code. (Tooling examples: ByteBuddy with Spring and JPA integrations).\n  b. Check for architectural rules. (Tooling examples: jQAssistant, ArchUnit).\n\n== Use Case: Express DDD concepts\n\nExample: A banking domain.\n\n=== Using the Annotation-Based Model\n\n[source,java]\n----\nimport org.jmolecules.ddd.annotation.*;\n\n@Entity\nclass BankAccount {\n\n    @Identity\n    final IBAN iban;\n\n    /* ... */\n\n}\n\n@ValueObject\nclass IBAN { /* ... */ }\n\n@ValueObject\nrecord Currency { /* ... */ }\n\n@Repository\nclass Accounts { /* ... */ }\n----\n\nWhen we take Ubiquitous Language serious, we want names (for classes, methods, etc.) that only contain words from the domain language.\nThat means the titles of the building blocks should not be part of the names.\nSo in a banking domain we don't want `BankAccountEntity`, `CurrencyVO` or even `AccountRepository` as types.\nInstead, we want `BankAccount`, `Currency` and `Accounts` – like in the example above.\n\nStill, we want to express that a given class (or other architectural element) is a special building block; i.e. uses a design pattern.\njMolecules provide a set of standard annotations for the building blocks known from DDD.\n\n=== Using the Type-Based Model\n\nAs an alternative to the above mentioned annotations, jMolecules also provides a set of interfaces, largely based on the ideas presented in John Sullivan's series https://scabl.blogspot.com/p/advancing-enterprise-ddd.html[\"Advancing Enterprise DDD\"].\nThey allow expressing relationships between the building blocks right within the type system, so that the compiler can help to verify model correctness and the information can also be processed by Java reflection more easily.\n\n* `Identifier` -- A type to represent types that are supposed to act as identifiers.\n* `Identifiable\u003cID\u003e` -- Anything that's exposing an identifier.\n* `Entity\u003cT extends AggregateRoot\u003cT, ?\u003e, ID\u003e extends Identifiable\u003cID\u003e` -- An entity, declaring to which `AggregateRoot` it belongs and which identifier it exposes.\n* `AggregateRoot\u003cT extends AggregateRoot\u003cT, ID\u003e, ID extends Identifier\u003e extends Entity\u003cT, ID\u003e` -- an aggregate root being an `Entity` belonging to itself exposing a dedicated `Identifier`\n* `Association\u003cT extends AggregateRoot\u003cT, ID\u003e, ID extends Identifier\u003e extends Identifiable\u003cID\u003e` -- an explicit association to a target `AggregateRoot`.\n\nThis arrangement gives guidance to modeling and allows to easily verify the following rules, potentially via reflection:\n\n* Enforced, dedicated identifier types per aggregate to avoid identifiers for different aggregates mixed up.\n* `AggregateRoot` must only refer to `Entity` instances that were declared to belong to it.\n* ``AggregateRoot``s and ``Entity``s must only refer to other `AggregateRoots` via `Association` instances.\n\nFor automated verification and runtime technology integration see https://github.com/xmolecules/jmolecules-integrations#jmoleculestechnology-integrations[jMolecules Integrations].\n\n=== Available Libraries\n* link:jmolecules-ddd[`jmolecules-ddd`] -- annotations and interfaces to express DDD building blocks (value objects, entities, aggregate roots etc.) in code.\n* link:jmolecules-events[`jmolecules-events`] -- annotations and interfaces to express the concept of events in code.\n* link:kmolecules-ddd[`kmolecules-ddd`] -- Kotlin-based flavor of `jmolecules-ddd` to mitigate Kotlin/Java interop issues for the type based model.\n\n== Use Case: Expressing architectural concepts\njMolecules provides annotations to describe higher-level architectural concepts following the styles of Layered, Onion, and Hexagonal Architectures.\nThey allow you to mark an entire package as a layer, ring, or one containing ports and adapters.\nThese would appear in the `package-info.java` file for each package that you want to annotate, e.g.:\n\n[source,java]\n.`package-info.java` for Domain layer:\n----\n@DomainLayer\npackage org.acmebank.domain;\n\nimport org.jmolecules.architecture.layered.*;\n----\n\n[source,java]\n.`package-info.java` for Application layer:\n----\n@ApplicationLayer\npackage org.acmebank.application;\n\nimport org.jmolecules.architecture.layered.*;\n----\n\nThat way, all classes in the respective package are considered to be part of the annotated layer, ring, or considered a port / adapter.\n\nAlternatively, classes can be annotated directly:\n\n[source,java]\n----\nimport org.jmolecules.architecture.layered.*;\n\n@DomainLayer\n@Entity\npublic class BankAccount { /* ... */ }\n\n@ApplicationLayer\n@Service\npublic class TransferMoney { /* ... */ }\n----\n\nCurrently, annotations for Layered, Onion, and Hexagonal Architecture exist.\n\n=== Available Libraries\n\n* link:jmolecules-architecture[`jmolecules-architecture`] -- annotations to express architectural styles in code.\n** link:jmolecules-architecture/jmolecules-cqrs-architecture[`jmolecules-cqrs-architecture`] -- CQRS architecture\n*** `@Command`\n*** `@CommandDispatcher`\n*** `@CommandHandler`\n*** `@QueryModel`\n** link:jmolecules-architecture/jmolecules-layered-architecture[`jmolecules-layered-architecture`] -- Layered architecture\n*** `@DomainLayer`\n*** `@ApplicationLayer`\n*** `@InfrastructureLayer`\n*** `@InterfaceLayer`\n** link:jmolecules-architecture/jmolecules-onion-architecture[`jmolecules-onion-architecture`] -- Onion architecture\n*** **Classic**\n**** `@DomainModelRing`\n**** `@DomainServiceRing`\n**** `@ApplicationServiceRing`\n**** `@InfrastructureRing`\n*** **Simplified** (does not separate domain model and services)\n**** `@DomainRing`\n**** `@ApplicationRing`\n**** `@InfrastructureRing`\n** link:jmolecules-architecture/jmolecules-hexagonal-architecture[`jmolecules-hexagonal-architecture`] -- Hexagonal architecture\n*** `@Application`\n*** `@(Primary|Secondary)Adapter`\n*** `@(Primary|Secondary)Port`\n\n== Use Case: Generate Technical Boilerplate Code\n\nThe jMolecules annotations and interfaces can be used to generate technical code needed to express the concept in a certain target technology.\n\n=== Available Libraries\n\n* https://github.com/xmolecules/jmolecules-integrations[Spring, Data JPA, Data MongoDB, Data JDBC, and Jackson integration] -- to make code using jMolecules annotations work out of the box in those technologies.\n\n== Use Case: Verify and Document Architecture\n\nThe jMolecules concepts expressed in code can be used to verify rules that stem from the concepts' definitions and  generate documentation.\n\n=== Available Libraries\n\n* https://github.com/jqassistant-plugin/jqassistant-jmolecules-plugin[jQAssistant plugin] -- to verify rules applying to the different architectural styles, DDD building blocks, CQRS and events. Also creates PlantUML diagrams from the information available in the codebase.\n* https://github.com/xmolecules/jmolecules-integrations/tree/main/jmolecules-archunit[ArchUnit rules] -- allow to verify relationships between DDD building blocks.\n* https://github.com/spring-projects/spring-modulith[Spring Modulith] -- supports detection of jMolecules components, DDD building blocks and events for module model and documentation purposes (see https://docs.spring.io/spring-modulith/reference/[the Spring Modulith documentation] for more information).\n\n== Installation\nTo use jMolecules in your project just declare a dependency to it.\nRelease binaries are available from the Maven central repository.\nTo avoid having to declare all versions explicitly, we recommend using the https://github.com/xmolecules/jmolecules-bom[`jmolecules-bom`] in your dependency management section.\n\n=== Maven\n\n[source,xml]\n----\n\u003cdependency\u003e\n  \u003cgroupId\u003eorg.jmolecules\u003c/groupId\u003e\n  \u003cartifactId\u003ejmolecules-ddd\u003c/artifactId\u003e\n  \u003cversion\u003e1.9.0\u003c/version\u003e\n\u003c/dependency\u003e\n----\n\n=== Gradle\n\n[source,groovy]\n----\nrepositories {\n  mavenCentral()\n}\ndependencies {\n  implementation(\"org.jmolecules:jmolecules-ddd:1.9.0\")\n}\n----\n\n== Developer information\n\n=== Release instructions\n\n* `mvn release:prepare -DscmReleaseCommitComment=\"$ticketId - Release version $version.\" -DscmDevelopmentCommitComment=\"$ticketId - Prepare next development iteration.\"`\n* `mvn release:perform -Dgpg.keyname=$keyname`\n","funding_links":[],"categories":["Java","开发框架","Projects","三、架构与框架（支撑大型应用）"],"sub_categories":["Architecture","1. 架构验证与设计"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxmolecules%2Fjmolecules","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fxmolecules%2Fjmolecules","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxmolecules%2Fjmolecules/lists"}