Second-Party Packages Explained: From Creation to Use
A second-party package is a Java jar shared across teams inside a company (like a private
@company/scopepackage on the frontend). Maven is the infrastructure that makes that private package ecosystem work (package management + build + repository + publish). The creation recipe: isolate what others consume (interfaces + DTOs) into a module or repo with Maven coordinates, minimize dependencies, keep the API stable,mvn deployto an internal registry, and let others depend via<dependency>.This piece uses frontend analogies so the jump from npm / monorepo land is easier. Business and org details are anonymized.
1. What is a second-party package
Industry practice splits dependencies by who writes them. Second-party is the middle class:
| Class | Who writes it | Examples | Frontend analogy |
|---|---|---|---|
| First-party | Modules inside this project | service / model / web modules in the same repo | Internal packages/* in a monorepo |
| Second-party | Other teams inside the company, published to an internal registry | company-common-utils, xxx-facade, xxx-boot-starter |
Private @company/scope packages |
| Third-party | External open source | fastjson, logback, jakarta.validation-api |
Public npm packages (react, lodash) |
In one line: a second-party package is a company-internal private package, distributed through an internal Maven registry.
A frontend command makes the mapping obvious:
tnpm install -g @company/cli --registry=https://registry.company-internal.cn
# ↑ private package ↑ internal registry ← frontend “second-party”
The Java counterpart:
<dependency>
<groupId>com.company.xxx</groupId> <!-- like @company scope -->
<artifactId>common-utils</artifactId> <!-- like the package name -->
<version>1.1.0</version> <!-- like ^1.2.3 -->
</dependency>
Typical second-party packages:
xxx-facade— an “interface definition” jar from a downstream service team. You get interfaces and DTOs only; the implementation stays invisible and is reached over RPC.common-utils/common-log— shared utilities / logging from a platform team.xxx-boot-starter— platform login / middleware starters.
2. How second-party packages relate to Maven
Maven is not a peer concept of “second-party packages”; it is the infrastructure that makes the pattern work. Three layers:
Maven = package manager + build tool + repository protocol ← roughly the npm stack
├── pom.xml ← package.json (declare dependencies)
├── internal registry ← private npm registry; stores second-party jars
├── resolution / transitive deps ← node_modules flattening + lockfile ideas
└── lifecycle (compile/test/package/deploy) ← npm scripts + publish
Frontend ↔ Java / Maven cheat sheet
| Frontend world | Java / Maven world |
|---|---|
| npm / tnpm | Maven / mvn |
| package.json | pom.xml |
| dependencies + versions | <dependency> + <version> |
| node_modules | ~/.m2/repository (local cache) |
| private npm registry | company Maven registry |
npm publish |
mvn deploy (to the private registry) |
| monorepo workspace packages | multi-module modules (first-party) |
@scope/xxx private packages |
second-party jars (groupId reverse-DNS, e.g. com.company.xxx) |
| public react/lodash | third-party jars (fastjson/logback) |
^1.2.3 ranges |
<version> + versions centralized in the parent |
Multi-module sketch
parent (0.0.1-SNAPSHOT, packaging=pom)
├── web
├── service
├── model
├── facade ← second-party module (published API)
└── (depends on other xxx-facade, common-utils, starters…)
Second-party versions are often ${xxx.version} placeholders—standard multi-module + central dependency management (declare versions in the parent’s properties / <dependencyManagement>), similar to a workspace root owning versions.
3. Where the code lives: three shapes
Shape A: an in-app facade module (most common)
myapp/ ← main application repo
├── pom.xml (parent: myapp-parent)
└── app/
├── facade/ ← module dedicated to external publishing
│ ├── pom.xml (artifactId=xxx-facade, version=${facade.version})
│ └── src/main/java/com/company/xxx/facade/rpc/
│ └── OrderService.java ← interface only
├── web/ service/ dal/ ← implementation modules
└── bootstrap/ ← boot module
Three critical details in facade/pom.xml:
<artifactId>xxx-facade</artifactId>
<version>${facade.version}</version> <!-- ① version independent of the app -->
<java.version>8</java.version> <!-- ② lower target JDK for downstream compatibility -->
<dependency>
<groupId>org.projectlombok</groupId>
<artifactId>lombok</artifactId>
<scope>provided</scope> <!-- ③ provided: not packaged; do not infect consumers -->
</dependency>
A pure external interface:
package com.company.xxx.facade.rpc;
/** RPC interface definition */
public interface OrderService {
String queryStatus(String orderId);
}
Why a separate module and a separate version? Because others depend on it:
- App upgrades must not thrash the facade API.
- Consumers depend on the “interface jar” only—not your whole service and its transitive tree.
- Interface vs implementation: facade holds interfaces + DTOs; implementations live in service—that is the RPC contract.
Shape B: a dedicated repository (purest second-party)
Shared utilities / SDKs with no business context often get their own Git repo:
common-utils/ ← standalone repo
├── pom.xml (groupId=com.company, artifactId=common-utils)
└── src/main/java/...
Shape C: fat jar / Spring Boot Starter (advanced)
Packages like xxx-boot-starter auto-configure via spring.factories / AutoConfiguration.imports and light up with near-zero config. Common for platform teams; higher authoring bar.
4. How to create a second-party package
Example: promotion-facade.
Step 1: repo and layout
promotion-facade/
├── pom.xml
└── src/main/java/com/company/promotion/facade/
├── api/PromotionQueryService.java ← public interface
└── model/PromotionDTO.java ← request/response DTO (Serializable)
Step 2: minimal pom.xml
<project>
<modelVersion>4.0.0</modelVersion>
<groupId>com.company</groupId> <!-- reverse-DNS of the company domain -->
<artifactId>promotion-facade</artifactId>
<version>1.0.0-SNAPSHOT</version> <!-- SNAPSHOT while developing; release as a fixed version -->
<properties>
<java.version>8</java.version> <!-- keep low for maximum downstream reach -->
<maven.compiler.source>8</maven.compiler.source>
<maven.compiler.target>8</maven.compiler.target>
</properties>
<dependencies>
<!-- as few as possible; DTOs often only need lombok (provided) -->
<dependency>
<groupId>org.projectlombok</groupId>
<artifactId>lombok</artifactId>
<scope>provided</scope>
</dependency>
</dependencies>
</project>
Step 3: interfaces + DTOs (the strict “door” others see)
package com.company.promotion.facade.api;
/** Promotion query RPC — the only entry consumers should see */
public interface PromotionQueryService {
PromotionDTO queryById(String id);
}
package com.company.promotion.facade.model;
import java.io.Serializable;
import lombok.Data;
/** Query response — RPC serialization needs Serializable */
@Data
public class PromotionDTO implements Serializable {
private static final long serialVersionUID = 1L; // serialization compatibility anchor
private String promotionId;
private String name;
}
5. Publish and consume
Publish to the internal registry
mvn clean deploy # package + upload to the internal Maven registry (needs credentials / ACL)
Production usually goes through CI:
- Configure a “publish second-party package” job with
mvn release(SNAPSHOT → release + tag + deploy). - Registry write access for the
groupIdis typically granted by a team admin.
How consumers depend
<dependency>
<groupId>com.company</groupId>
<artifactId>promotion-facade</artifactId>
<version>1.0.0</version>
</dependency>
With SOFA RPC, a consumer annotates the interface with @SofaReference and at runtime reaches your service-side Bean that implements PromotionQueryService—the interface lives in their code; the implementation runs on your machines. That is the core value of a facade second-party package + RPC.
6. Rules that are special to second-party packages
| Rule | Why | Frontend analogy |
|---|---|---|
| Stable, backward-compatible APIs | Consumers rarely upgrade in lockstep; signature breaks explode downstream | Do not casually change npm package exports |
| Interfaces + DTOs only—never implementations / business logic | Implementation stays server-side; leaking it couples and bloats the jar | Ship .d.ts without shipping the implementation |
Minimize dependencies; prefer scope=provided |
Your deps become their transitive deps → jar hell | Same spirit as peerDependencies |
Serializable + serialVersionUID |
Hard requirement for cross-process RPC; field churn can break deserialization | Protocol-layer constraints |
| Version discipline: SNAPSHOT → release | Develop on 1.0.0-SNAPSHOT, lock 1.0.0 when stable |
next tag → formal publish |
Keep java.version low (8/11) |
Downstream may still run older JVMs | Conservative browserslist for a library |
Reverse-DNS groupId + centralized versions |
Unique coordinates; multi-module versions owned by parent | @scope + workspace root releases |
| Publish via pipeline + ACL | Private registries run security / compliance checks | npm publish 2FA + scoped permissions |
The classic production incident: breaking changes
Never “upgrade” a second-party package by breaking field or method signatures. Add fields/methods, deprecate old ones (
@Deprecated), and delete only after N versions. You do not know how many consumers are running; deleting a method surfaces as a runtimeNoSuchMethodErrorwith no compile-time safety net—the most common second-party incident class.
7. Glossary
| Term | One line |
|---|---|
| First-party package | Dependency between modules of this project (same-repo modules) |
| Second-party package | Company-internal shared jar ≈ private @scope/xxx |
| Third-party package | External open-source jar (fastjson / logback, …) |
| Maven | Package management + build + repository + publish (≈ npm stack) |
| pom.xml | Maven project descriptor (≈ package.json) |
| groupId:artifactId:version | Package coordinates (≈ scope + name + version) |
| Internal Maven registry | Where second-party jars live (≈ private npm registry) |
mvn deploy |
Publish to the registry (≈ npm publish) |
| facade module | Module that publishes only interfaces + DTOs |
| SNAPSHOT | Unstable development version (≈ next tag) |
@SofaReference |
SOFA RPC annotation for a remote interface reference |
| Transitive dependency | Your dependencies are inherited by consumers (scope controls leakage) |
Further reading
Related backend engineering posts: Database transactions · Idempotency · Domain-Driven Design (DDD). Interface and contract boundaries also pair with how DDD exposes domain models.
Comments